home *** CD-ROM | disk | FTP | other *** search
/ The CICA Windows Explosion! / The CICA Windows Explosion! - Disc 2.iso / programr / cxtw107.zip / SXT.DOC < prev    next >
Text File  |  1995-07-20  |  230KB  |  5,369 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.                   SXT (TM) SOFTWARE EXPLORATION TOOLS
  11.  
  12.  
  13.  
  14.                   CXT (TM) C EXPLORATION TOOLS
  15.  
  16.                     * CFT (TM) C FUNCTION TREE GENERATOR
  17.                     * CST (TM) C STRUCTURE TREE GENERATOR
  18.  
  19.  
  20.                   DXT (TM) DBASE EXPLORATION TOOLS
  21.  
  22.                     * DFT (TM) DBASE FUNCTION TREE GENERATOR
  23.  
  24.  
  25.                   FXT (TM) FORTRAN EXPLORATION TOOLS
  26.  
  27.                     * FFT (TM) FORTRAN FUNCTION TREE GENERATOR
  28.  
  29.  
  30.                   LXT (TM) LISP EXPLORATION TOOLS
  31.  
  32.                     * LFT (TM) LISP FUNCTION TREE GENERATOR
  33.  
  34.  
  35.  
  36.  
  37.                   SXT command line versions
  38.                   SXTWIN Windows versions
  39.  
  40.  
  41.  
  42.                   July 1995
  43.  
  44.                   Copyright (C) Juergen Mueller (J.M.) 1988-1995.
  45.                   All Rights Reserved World-Wide.
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.                                       - 1 -
  62.  
  63.  
  64.                              DISCLAIMER OF WARRANTY
  65.  
  66.         THIS  SOFTWARE  AND  ACCOMPANYING  WRITTEN  MATERIAL   (INCLUDING
  67.         INSTRUCTIONS  FOR  USE) IS PROVIDED "AS IS" WITH NO WARRANTIES OF
  68.         ANY  KIND,   EITHER  EXPRESS  OR  IMPLIED,   INCLUDING,   WITHOUT
  69.         LIMITATION, THE WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS
  70.         FOR  A  PARTICULAR  PURPOSE,  NONINFRINGEMENT,  OR ARISING FROM A
  71.         COURSE OF DEALING, USAGE OR TRADE PRACTICE. THE ENTIRE RISK AS TO
  72.         THE RESULTS AND PERFORMANCE OF THE SOFTWARE IS WITH YOU.
  73.  
  74.         THE AUTHOR AND COPYRIGHT HOLDER  SHALL  HAVE  NO  LIABILITY  WITH
  75.         RESPECT  TO THE INFRINGEMENT OF COPYRIGHTS,  TRADE SECRETS OR ANY
  76.         PATENTS BY THIS SOFTWARE OR ANY PART THEREOF.
  77.  
  78.         IN NO EVENT WILL THE AUTHOR AND COPYRIGHT HOLDER  BE  LIABLE  FOR
  79.         DAMAGES,  INCLUDING  ANY  LOST  PROFITS,  LOST  MONIES,  OR OTHER
  80.         DIRECT,  INDIRECT,  GENERAL,  SPECIAL,  INCIDENTAL,  EXEMPLARY OR
  81.         CONSEQUENTIAL  DAMAGES  ARISING  IN  ANY  WAY  OUT  OF THE USE OR
  82.         INABILITY TO USE THIS PROGRAM (INCLUDING,  BUT  NOT  LIMITED  TO,
  83.         PROCUREMENT   OF   SUBSTITUTE   GOODS   OR   SERVICES,   BUSINESS
  84.         INTERRUPTION,  LOSS OF DATA OR DATA BEING RENDERED INACCURATE  OR
  85.         LOSSES  SUSTAINED  BY  YOU  OR  THIRD PARTIES OR A FAILURE OF THE
  86.         PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS) AND ON ANY THEORY  OF
  87.         LIABILITY, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR
  88.         FOR ANY CLAIM BY ANY OTHER PARTY.
  89.  
  90.  
  91.                                  ACKNOWLEDGEMENT
  92.  
  93.         BY  USING  THIS  SOFTWARE YOU ACKNOWLEDGE THAT YOU HAVE READ THIS
  94.         LIMITED WARRANTY AND ACCOMPANYING  REMARKS,  UNDERSTAND  IT,  AND
  95.         AGREE  TO  BE  BOUND BY ITS TERMS AND CONDITIONS.  YOU ALSO AGREE
  96.         THAT THIS IS THE COMPLETE AND EXCLUSIVE  STATEMENT  OF  AGREEMENT
  97.         BETWEEN   THE  PARTIES  AND  SUPERSEDE  ALL  PROPOSALS  OR  PRIOR
  98.         AGREEMENTS, ORAL OR WRITTEN, AND ANY OTHER COMMUNICATIONS BETWEEN
  99.         THE PARTIES  RELATING  TO  THE  SUBJECT  MATTER  OF  THE  LIMITED
  100.         WARRANTY. YOU AGREE THAT THIS NOTICE APPLIES TO ALL FILES IN THIS
  101.         SOFTWARE DISTRIBUTION.
  102.  
  103.  
  104.         You  are expressly prohibited from selling this software or parts
  105.         of it in any form,  circulate it in any  incomplete  or  modified
  106.         form, distribute it with another product (except as Shareware) or
  107.         removing  this  notice.  No  one  may  modify or patch any of the
  108.         executable files in any  way,  including,  but  not  limited  to,
  109.         decompiling,  disassembling or otherwise reverse engineering this
  110.         software in whole or part.
  111.  
  112.         The documentation may be distributed verbatim,  but  changing  is
  113.         not allowed.  The information and specifications in this document
  114.         are subject to change without notice.
  115.  
  116.         THIS  VERSION  OF  THE  DOCUMENTATION,   SOFTWARE  AND  COPYRIGHT
  117.         SUPERSEDES  ALL PREVIOUS VERSIONS.  THIS SOFTWARE AND ITS RELATED
  118.         DOCUMENTATION MAY CHANGE WITHOUT NOTICE.
  119.  
  120.  
  121.  
  122.                                       - 2 -
  123.  
  124.  
  125.         This software and documentation is Copyright (C) 1988-1995 by
  126.  
  127.                   Juergen Mueller
  128.                   Aldingerstrasse 22
  129.                   D-70806 Kornwestheim
  130.                   GERMANY
  131.  
  132.                   Email address: juergen.mueller@isw.uni-stuttgart.de
  133.  
  134.  
  135.         THERE ARE NO RELATIONS BETWEEN THE AUTHORS PROFESSIONAL WORK  AND
  136.         THE  SXT  DEVELOPMENT.  THE  SXT  PROJECT IS AND HAS EVER BEEN AN
  137.         INDEPENDENT PRIVATE PROJECT OF THE  AUTHOR  AND  IS  WRITTEN  AND
  138.         MAINTAINED IN HIS FREE TIME.
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.                                       - 3 -
  184.  
  185.  
  186.                                      LICENSE
  187.  
  188.         This software is not public domain or free software, but is being
  189.         distributed  as  shareware.  It  is  protected  by  copyright and
  190.         distributed under this licence restricting its use.
  191.  
  192.         Non-registered users of  this  software  are  granted  a  limited
  193.         license  for  a 30-day evaluation period starting from the day of
  194.         the first use to make an evaluation copy for trial  use  for  the
  195.         express  purpose of determining whether this software is suitable
  196.         for their needs.  At the end of  this  trial  period  you  should
  197.         either register your copy or discontinue using this software. The
  198.         use  of  unregistered  copies  of  this software,  outside of the
  199.         initial 30-day  trial,  by  any  person,  business,  corporation,
  200.         government agency or any other entity is strictly prohibited.
  201.  
  202.         This means that if you use this software, then you should pay for
  203.         your  copy.   This  software  is  not  free,  but  you  have  the
  204.         opportunity to try it before you buy it.  Either pay for  it,  or
  205.         quit  using  it.  A registration entitles you to use your copy of
  206.         this software on any and all computers available to you. If other
  207.         people  have  access  to  this  software  or  may  use  it,  then
  208.         additional copies or a site license should be purchased.
  209.  
  210.         All  users  are  granted  a limited license to copy this software
  211.         only for the trial  use  of  others  and  subject  to  the  above
  212.         limitations.  This license does not include distribution, selling
  213.         or copying of this software package in connection with any  other
  214.         product  or  service  or  for  distribution  in any incomplete or
  215.         modified form. Operators of electronic bulletin board systems and
  216.         software servers (like Internet FTP-Servers)  are  encouraged  to
  217.         post this software for downloading by their users, as long as the
  218.         above conditions are met.
  219.  
  220.         This package is expected to be distributed as shareware,  but the
  221.         fees paid for "distribution" costs (disk,  CD-ROM)  are  strictly
  222.         exchanged  between  the  distributor  and the recipient,  and the
  223.         author makes no express or implied warranties about  the  quality
  224.         or integrity of such indirectly acquired copies. Distributors and
  225.         users  may  obtain  the  package  directly  from  the  author  by
  226.         following the ordering procedures in the REGISTER files.
  227.  
  228.  
  229.                               REGISTRATION REMINDER
  230.  
  231.         Unregistered copies of this software are 100% fully functional. I
  232.         make them this way so that you can have a real look at them,  and
  233.         then decide whether they fit your needs or not. This work depends
  234.         on your honesty.  If you use it, I expect you to pay for it. When
  235.         you pay for the shareware you like,  you  are  voting  with  your
  236.         pocketbook,  and will encourage me and other shareware authors to
  237.         develop more of these kinds of products.
  238.  
  239.  
  240.                  THANK YOU FOR SUPPORTING THE SHAREWARE CONCEPT
  241.  
  242.  
  243.  
  244.                                       - 4 -
  245.  
  246.  
  247.                   TABLE OF CONTENTS
  248.  
  249.                   1    THE SXT SOFTWARE EXPLORATION TOOLS
  250.                   2    GENERAL INTRODUCTION
  251.                   3    PROGRAM DESCRIPTION
  252.                   4    LANGUAGE IMPLEMENTATIONS
  253.                   4.1  C-LANGUAGE IMPLEMENTATION AND C-PREPROCESSOR
  254.                   4.2  C++ LANGUAGE IMPLEMENTATION
  255.                   4.3  DBASE SOURCE CODE
  256.                   4.4  FORTRAN SOURCE CODE
  257.                   4.5  LISP SOURCE CODE
  258.                   4.6  ASSEMBLER SOURCE CODE
  259.                   5    DATABASE GENERATION
  260.                   6    PROGRAM LIMITATIONS
  261.                   7    SXT OPTIONS
  262.                   8    OUTPUT DESCRIPTION AND INTERPRETATION
  263.                   9    INTEGRATION INTO PROGRAM DEVELOPMENT ENVIRONMENTS
  264.                   10   TOOLS FOR DATABASE PROCESSING
  265.                   11   IMPROVING EXECUTION SPEED
  266.                   12   TROUBLE SHOOTING
  267.                   13   FREQUENTLY ASKED QUESTIONS
  268.                   14   REFERENCES
  269.                   15   TRADEMARKS
  270.  
  271.                   APPENDIX 1: C/C++ PRECOMPILER DEFINES
  272.                   APPENDIX 2: RESERVED C/C++ KEYWORDS
  273.                   APPENDIX 3: RESERVED FORTRAN KEYWORDS
  274.                   APPENDIX 4: EFFICIENCY
  275.                   APPENDIX 5: REVIEWS
  276.                   APPENDIX 6: SYSTEM REQUIREMENTS
  277.                   APPENDIX 7: INSTALLATION
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.                                       - 5 -
  306.  
  307.  
  308.         1    THE SXT SOFTWARE EXPLORATION TOOLS
  309.  
  310.         The SXT Software Exploration Tools are a collection  of  software
  311.         analysis  tools  providing  a similar functionality for different
  312.         programming languages.
  313.  
  314.         The following packages are currently available:
  315.  
  316.         * CXT - C Exploration Tools:
  317.           CFT - C Function Tree Generator
  318.              Tool to analyse and display the function call  relationships
  319.              within the source code of C/C++ programs.
  320.           CST - C Structure Tree Generator
  321.              Tool    to   analyse   and   display   the   structure/class
  322.              relationships within the source code of C/C++ programs.
  323.  
  324.         * DXT - DBASE Exploration Tools:
  325.           DFT - DBASE Function Tree Generator
  326.              Tool to analyse and display the function call  relationships
  327.              within  the  source  code  of  DBASE,  CLIPPER '87 and other
  328.              XBASE-like programs.
  329.  
  330.         * FXT - FORTRAN Exploration Tools:
  331.           FFT - FORTRAN Function Tree Generator
  332.              Tool to analyse and display the function call  relationships
  333.              within the source code of FORTRAN programs.
  334.  
  335.         * LXT - LISP Exploration Tools:
  336.           LFT - LISP Function Tree Generator
  337.              Tool  to analyse and display the function call relationships
  338.              within the source code of LISP and SCHEME programs.
  339.  
  340.         Each  of  these  packages  consists  of  the   analysis   program
  341.         ("Analyser")  and  a recall program ("Navigator") to retrieve the
  342.         analysis  results  which  can  be  stored  in  a  database,  plus
  343.         documentation and additional macros to integrate these tools into
  344.         popular editors like BRIEF, QEDIT or MicroEMACS.
  345.  
  346.         Each of these packages is available for the following systems:
  347.  
  348.              SXT command line versions:
  349.              * DOS real mode               (shareware release)
  350.              * DOS 386 protected mode      (registered users only)
  351.              * Windows NT text mode        (registered users only)
  352.              * OS/2 text mode              (registered users only)
  353.  
  354.              SXTWIN Windows versions:
  355.              * Windows 3.1                 (shareware release)
  356.              * Windows 32 bit (Win32s)     (registered users only)
  357.  
  358.         There  are  no  differences  in  the  functionality  between  the
  359.         versions for the different systems.
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.                                       - 6 -
  367.  
  368.  
  369.         There are no plans to port the SXT programs to other platforms or
  370.         operating systems like Apple MacIntosh, UNIX (SCO, Solaris,  AIX,
  371.         HP-UX,  Linux,  ...),  Atari or Amiga. The source code of the SXT
  372.         programs is not available.
  373.  
  374.         IMPORTANT NOTICE ABOUT THIS DOCUMENT
  375.  
  376.         Although this document is mainly based on the description for the
  377.         CXT programs CFT and CST (which were up to version 2.13 the  only
  378.         public  available SXT programs) and therefore very C/C++ related,
  379.         the description  applies  in  the  same  way  to  all  other  SXT
  380.         packages.  The  names  CXT/CXTWIN  resp.  CFT/CST,  CFTN/CSTN and
  381.         CFTWIN/CSTWIN can  be  simply  exchanged  by  the  similar  other
  382.         product names DXT/DFT,  FXT/FFT or LXT/LFT.  Where necessary, the
  383.         specific  differences  of  the  SXT   packages   are   described,
  384.         especially in the chapter describing the options.  I have done it
  385.         this way to ensure an overall consistency,  to keep  all  related
  386.         things  together  and  to  reduce  the  efforts  for  writing and
  387.         maintaining this document.
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.                                       - 7 -
  428.  
  429.  
  430.         2    GENERAL INTRODUCTION
  431.  
  432.         The SXT programs are powerful  program  development,  maintenance
  433.         and   documentation  tools.   They  are  primarily  intended  for
  434.         analysing  large  programs,   where  it  is  difficult,   if  not
  435.         impossible, for the programmer to find the structure of the whole
  436.         program.   They   allow  the  analysis  of  the  source  code  of
  437.         applications,  no matter how big or complex  they  are.  The  SXT
  438.         programs  are also very useful to explore unknown source code and
  439.         to get  complete  overview  about  its  internal  structure.  The
  440.         re-engineering  of  old  and/or  undocumented source code becomes
  441.         much easier with these programs. The tools help the programmer to
  442.         analyse,  identify,  locate and  access  all  parts  of  a  large
  443.         software  system.  They  are  designed to support software reuse,
  444.         maintenance and reliability.
  445.  
  446.         By preprocessing,  scanning  and  analysing  the  entire  program
  447.         source  code  as a single unit,  these programs build an internal
  448.         representation of the function call  hierarchy  (CFT,  DFT,  FFT,
  449.         LFT)  and  of  the data structure relations (CST).  The resulting
  450.         output shows from a global perspective the interdependencies  and
  451.         hierarchical structure between the functions or data types of the
  452.         whole, multi file, software project. Several features and options
  453.         allow  the  user  to  customise  the generated hierarchy calltree
  454.         output and to get a large set of  useful  information  about  the
  455.         source code. The hierarchy structure is always up-to-date because
  456.         it  relies  on  the original source code as the primary source of
  457.         information.  Written software documentation often  differs  from
  458.         that what really has been coded, so the source code itself is the
  459.         ultimate documentation.
  460.  
  461.         An  important  feature is the database generation.  It allows the
  462.         recalling of information without reprocessing  the  source  code.
  463.         The  database  can  again  be  read  in by CFT and CST to produce
  464.         different outputs or to add new files to  the  database.  Special
  465.         recall  programs  called  CFTN  and CSTN allow fast searching for
  466.         items in the database.  These programs can  be  used  within  any
  467.         environment,  for  example on the DOS command line or from inside
  468.         editors like BRIEF,  QEDIT or MicroEMACS (DOS  and  WINDOWS),  to
  469.         provide  a full software project management system with access to
  470.         all functions  and  data  types  with  just  a  keystroke.  These
  471.         features  make  a  comfortable "hypertext source code browser and
  472.         locator" system out of  your  editor.  A  project  consisting  of
  473.         several   files  appears  to  the  developer  as  if  it  were  a
  474.         'whole-part' of software. The developer can walk through programs
  475.         and trace the logic without having to  memorize  the  directories
  476.         and  files  where functions or data types are defined and called.
  477.         The SXT windows versions provide  a  similar  functionality  with
  478.         DLL's for database access from other programs.
  479.  
  480.         Displaying   and  printing  a  graphical  representation  of  the
  481.         analysis results as a call graph is not  directly  supported  bye
  482.         the SXT programs.  However,  owners of RATIONAL ROSE,  a powerful
  483.         software   development   case   tool   supporting    the    Booch
  484.         Object-Oriented Analysis and Design (OOAD) method,  can (mis-)use
  485.  
  486.  
  487.  
  488.                                       - 8 -
  489.  
  490.  
  491.         this tool for  such  purposes.  The  SXT  programs  can  generate
  492.         compatible  output  which  can be imported by Rational Rose.  See
  493.         option -RATIONAL for a detailed description.
  494.  
  495.         The SXT programs can generate the calltree and other  information
  496.         in HTML (HyperText Markup Language) format which can be viewed by
  497.         any  WWW  (World Wide Web) Browser like NCSA Mosaic,  Netscape or
  498.         MS-WinWord 6.0 Internet Assistant.  The  HTML  document  contains
  499.         hypertext  links  and allows jumps to item definitions within the
  500.         document. See option -HTML for more information.
  501.  
  502.         Every SXT program can generate the calltree and other information
  503.         also in RTF (Rich Text Format) format which can  be  imported  by
  504.         word  processors.  The  RTF output can be used to compile Windows
  505.         helpfiles with the Windows Help Compiler which can be viewed with
  506.         WINHELP.  The RTF document contains hypertext  links  and  allows
  507.         jumps  to  item definitions within the document.  See option -RTF
  508.         for more information.
  509.  
  510.         Listings of all functions/data types and source files can also be
  511.         written as formatted ASCII text files and can be  used  as  input
  512.         for   other   programs   like   word  processors  or  spreadsheet
  513.         calculators.
  514.  
  515.         A useful option of CST is the possibility to  generate  a  source
  516.         file   with   which   size   and  byte  offset  calculations  for
  517.         structures/unions and their members can be performed. This option
  518.         is useful especially to support any kind of  error  searching  or
  519.         hardware  debugging,  for example with an ICE (Integrated Circuit
  520.         Emulator),  or if data structures have to  be  exchanged  between
  521.         different hardware platforms with different data alignment.
  522.  
  523.         CFT  can  also  be used to analyse "C"-like languages as they are
  524.         used  by  several  commercial  programs.  The  macro  programming
  525.         languages of the BRIEF, EPSILON and ME editors are such languages
  526.         and can be handled by CFT.
  527.  
  528.         The  resulting output files can be used for various purposes like
  529.         development or documentation.  For registered users there are  no
  530.         restriction limits in using them for their own work.
  531.  
  532.         CFT  and  CST  have  been  used  and tested since 1989 in several
  533.         projects with applications ranging from single source files  over
  534.         medium  sized  projects  (like  CFT,  CST and the other SXT tools
  535.         themselves) up to very large software projects with  hundreds  of
  536.         source and include files (mixed C and assembler code),  more than
  537.         6 MB of source code,  more than 210000 lines,  2300 functions and
  538.         700 data types.
  539.  
  540.         A lot of public available C/C++ sources (e.g. GNU-C/C++ compiler,
  541.         GNU-C library,  GNU-EMACS,  MicroEMACS, NCSA TCP/IP communication
  542.         software package, SUIT - The Simple User Interface Toolkit, NIHCL
  543.         - The  National  Institute  of  Health  C++  class  library,  F2C
  544.         Fortran-to-C translator, several projects from Dr. Dobbs Journal,
  545.         Microsoft  sample  code  (MFC))  were  processed  (with sometimes
  546.         surprising results!) during the development and have been used to
  547.  
  548.  
  549.                                       - 9 -
  550.  
  551.  
  552.         test  and  improve  the   features,   reliability,   correctness,
  553.         robustness  and  execution  speed  of CFT,  CST and their related
  554.         utilities.
  555.  
  556.         Although the other SXT packages are much newer than CFT and  CST,
  557.         they  all  are closely related.  The CXT programs are used as the
  558.         common base for all other packages.
  559.  
  560.  
  561.  
  562.  
  563.  
  564.  
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.                                      - 10 -
  611.  
  612.  
  613.         3    PROGRAM DESCRIPTION
  614.  
  615.         CFT builds a hierarchy calltree of every function with the called
  616.         functions in it's own function block.  These functions are  again
  617.         used as a starting point for subsequent function blocks. Starting
  618.         the  calltree  with  the  "main"-function  it  will  display  the
  619.         complete  function  flow  chart  and   the   function   hierarchy
  620.         dependency  of  the  whole  application  with  all  user  defined
  621.         functions and the called library functions.  Prototyped but never
  622.         defined or called functions are also detected. Recursive calls of
  623.         functions  are  recognised and displayed,  even over several call
  624.         levels.  Repeated calls of previously displayed functions in  the
  625.         output  calltree  are detected and a message will be given with a
  626.         reference to their first appearance.  This prevents the output of
  627.         complete subtrees displayed earlier. Overloaded C++ functions and
  628.         operators  are  recognised  and  displayed  with  the  number  of
  629.         overloadings.
  630.  
  631.         CST acts similar to CFT but it works on  data  types  like  basic
  632.         types,  structures,  unions,  enumerations  and C++ classes.  CST
  633.         builds a hierarchy calltree of every  structure  and  union  data
  634.         type  with  their internal elements and their related data types.
  635.         If these data types are again structures, unions or classes,  the
  636.         substructures will again be displayed.  CST recognises data types
  637.         defined by 'typedef' and derived from other data types.  The type
  638.         names  corresponding  to the same basic type are displayed in the
  639.         output file as 'alias' names for their  common  basic  data  type
  640.         name.  Every  feature  of  CFT  like  the  detection of recursive
  641.         declared  structures  and  unions,   references   to   previously
  642.         displayed data types and others are available and act similar.
  643.  
  644.         Every  function  (CFT)  and data type (CST) can be displayed with
  645.         the name of the source file and  the  line  number  where  it  is
  646.         defined.  The  output can be customised to display the tree chart
  647.         as a call-tree ("CALLER-CALLEE"-relation: "WHO CALLS WHOM") or as
  648.         a  caller-tree  ("CALLEE-CALLER"-relation:  "WHO  IS  CALLED   BY
  649.         WHOM"). This feature allows the user to determine which functions
  650.         are  called  from  a  specific  function  or  which functions are
  651.         callers of a specific function.
  652.  
  653.         The function and data type extraction from  the  source  code  is
  654.         done  by scanning and parsing the source.  There is absolutely no
  655.         need for the programmer  to  mark  functions  or  data  types  of
  656.         interest,   for  example  with  special  keywords,  starting  the
  657.         definitions at the  beginning  of  a  line  or  to  use  comments
  658.         containing  special  marks,  as  it is necessary for other source
  659.         code analysers and browsers. CFT,  CST and the other SXT programs
  660.         do not need these work-arounds,  any source code can be processed
  661.         without previous work.  These tools are also compiler independent
  662.         because they can be customised to support any kind of compiler.
  663.  
  664.         Since  the  SXT  programs  always  make  a static analysis of the
  665.         program source code,  they are not able to detect references  due
  666.         to  the expansion of a macro definition during runtime.  This has
  667.         to be considered for DBASE and LISP  programs  which  allow  such
  668.         dynamic features.  The same restrictions apply also to the use of
  669.  
  670.  
  671.                                      - 11 -
  672.  
  673.  
  674.         function  pointers  for  C/C++  and  function  names  as   formal
  675.         parameters  in  FORTRAN  which  cannot be resolved for call graph
  676.         generation.
  677.  
  678.         Several  useful  information  and  software  metrics  about   the
  679.         processed  source  code  and  the included files can be generated
  680.         like
  681.  
  682.         -    file size and comment size in bytes for every file,
  683.         -    number of source code lines for every file,
  684.         -    number of included files for every source file,
  685.         -    total effective number of scanned bytes and lines for  every
  686.              source  file  and its included files,  if files are included
  687.              multiple times, this will influence the calculations,
  688.         -    for every defined function the number of lines, the code and
  689.              comment size in bytes,  the number of bytes  per  line,  the
  690.              number  of  functions  called,  the  number  of flow control
  691.              statements (if,  else,  for,  while,  case,  default,  goto,
  692.              return,  exit),  the  maximum brace nesting level and if the
  693.              function is used only inside the file,
  694.         -    for  every  defined  structure/union  the  total  number  of
  695.              elements  and  the  number  of elements which are themselves
  696.              structures/unions,
  697.         -    file function or data type reference list for every file,
  698.         -    total number of displayed,  defined,  undefined or  multiple
  699.              defined functions and data types,
  700.         -    location of multiple defined functions and data types,
  701.         -    location of overloaded C++ functions,
  702.         -    source  file  -  include  file dependencies for every source
  703.              file (MAKE-dependencies),
  704.         -    source file - include  file  hierarchy  tree  (include  file
  705.              relations),
  706.         -    final statistical summary for all files,
  707.         -    cross  reference  of  every occurrence for every function or
  708.              data type,
  709.         -    parent/children relationship for  every  function  and  data
  710.              type,
  711.         -    critical  function  call path/structure nesting with deepest
  712.              non-recursive nesting level (unlimited tree depth),
  713.         -    C++ class inheritance tree,
  714.         -    support for C structure/union byte offset calculation,
  715.         -    FORTRAN subroutine CALLs,
  716.         -    FORTRAN COMMON blocks,
  717.         -    generation of description files for  call/inheritance  graph
  718.              visualisation with the RATIONAL ROSE CASE tool,
  719.         -    generation  of  HTML-output  for calltree visualisation with
  720.              WWW Browsers like NCSA Mosaic,  Netscape or  MS-WinWord  6.0
  721.              Internet Assistant,
  722.         -    generation  of  RTF-output for import to word processors and
  723.              for compiling to Windows Helpfiles from it
  724.  
  725.         The resulting hierarchy structure chart is another representation
  726.         for a directed call graph.  A directed  call  graph  consists  of
  727.         nodes  (functions or data types) and connections (call relations)
  728.         between these nodes.  The number of nodes and  connections  which
  729.  
  730.  
  731.  
  732.                                      - 12 -
  733.  
  734.  
  735.         are  necessary  to transform the hierarchy structure chart into a
  736.         directed call graph will also  be  calculated  as  an  additional
  737.         information about the system complexity.
  738.  
  739.         A  large  number  of options to control the program execution and
  740.         the output generation are available and can  be  defined  on  the
  741.         command  line,  with  interactive dialog windows (applies only to
  742.         Windows versions),  by command files or by defining  them  in  an
  743.         environment variable used by the program.
  744.  
  745.         CFT,  CST and the other SXT programs can be directly invoked from
  746.         inside editors or integrated development  environments  like  the
  747.         Borland  C++ IDE.  Detailed examples for the integration together
  748.         with necessary macro or batch files are given.  The  SXT  windows
  749.         versions  provide  DLL's  (Dynamic  Link Libraries) to access the
  750.         generated databases and to retrieve information.  These DLL's can
  751.         be  used  with user developed programs e.g.  written in C/C++ and
  752.         Visual Basic, or from other Windows applications like MS-Word for
  753.         Windows, MS-Excel, MS-Access and others.
  754.  
  755.  
  756.  
  757.  
  758.  
  759.  
  760.  
  761.  
  762.  
  763.  
  764.  
  765.  
  766.  
  767.  
  768.  
  769.  
  770.  
  771.  
  772.  
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.  
  788.  
  789.  
  790.  
  791.  
  792.  
  793.                                      - 13 -
  794.  
  795.  
  796.         4    LANGUAGE IMPLEMENTATIONS
  797.  
  798.         4.1  C-LANGUAGE IMPLEMENTATION AND C-PREPROCESSOR
  799.  
  800.         The ISO/ANSI C language  standard  ISO/IEC  9899:1990  (E)  resp.
  801.         X3.159-1989-ANSI  C  as  described  in  several  books  about the
  802.         C-language (see references) was used as a development  base.  The
  803.         reserved  keywords  being  recognised  are  not only the original
  804.         ISO/ANSI C keywords but were also  taken  from  several  compiler
  805.         implementations  like  Microsoft,  Borland  or  GNU and their own
  806.         special language  extensions.  The  books  "The  C++  Programming
  807.         Language" and "The Annotated C++ Reference Manual" (ARM) together
  808.         with  information  about the work of the ANSI C++ committee X3J16
  809.         resp.  the ISO/IEC working group SC22 WG21 were used for the  C++
  810.         keywords.  Another  major  source  was  the AT&T C++ release 2.1.
  811.         Compiler  specific  extensions  especially  from  GNU  are   also
  812.         recognised.
  813.  
  814.         A  complete  list of all reserved keywords is show in appendix 2.
  815.         The large set of keywords may lead to  some  slight  problems  in
  816.         situations  where  a  keyword  is  not  used  as itself but as an
  817.         identifier name,  for example a C++ keyword used as an identifier
  818.         in C.
  819.  
  820.         During a normal file scan,  precompiler defines are, if possible,
  821.         handled as if a real precompiler would be present,  but this  can
  822.         cause  some  trouble  with '#if',  '#ifdef' and other precompiler
  823.         controls which are not evaluated.  Also the block nesting  level,
  824.         which will be monitored by the source code scanner, may not be at
  825.         level  0  at  the  end  of  the  file because of such precompiler
  826.         controls. To avoid such things,  a built-in C-preprocessor allows
  827.         the  complete  preprocessing of the source code and include files
  828.         for several compiler types as an additional option (-P).
  829.  
  830.         Preprocessing or not is a little bit controversial because it can
  831.         either result in a loss of information  if  macros  are  used  to
  832.         change the program behaviour and hide function calls, it can lead
  833.         to  errors during file scanning or it can change the function and
  834.         data type information  obtained  from  the  code  which  may  not
  835.         exactly correspond to the visible source code.  Preprocessing can
  836.         be an advantage or not, so the user has to decide whether he does
  837.         it or not (see options -P, -I, -E for more information).
  838.  
  839.         The  preprocessor  handles  the  defines  for  Microsoft  C  5.1,
  840.         Microsoft  C/C++  7.0,  Microsoft  Visual  C++  1.5 professional,
  841.         Microsoft Visual C++ 1.1 for Windows NT,  Turbo C++ 1.0,  Borland
  842.         C++  2.0,  Borland C++ 3.1,  Borland C++ 1.0 for OS/2,  GNU-C and
  843.         Intel 80960 C compiler iC960  3.0  and  all  memory  models  (not
  844.         necessary  for GNU-C and I960) or CPU architectures for the Intel
  845.         80960 32 bit RISC processor (KA,  KB,  SA,  SB,  MC,  CA).  Other
  846.         compiler  types  can  be customised with the -B and the -D and -U
  847.         options.  The default ISO/ANSI C  predefined  macros  '__FILE__',
  848.         '__LINE__',    '__DATE__',    '__TIME__'    are   generated   for
  849.         preprocessing.   The  macro  '__STDC__'  is  NOT  defined   (some
  850.         compilers  test  with  '#ifndef __STDC__'),  so that non standard
  851.         ISO/ANSI C extensions in the processed code are allowed. Defining
  852.  
  853.  
  854.                                      - 14 -
  855.  
  856.  
  857.         '-D__STDC__=1' forces ISO/ANSI C conforming output  (if  used  by
  858.         the  scanned  source  code,  of  course!).  Additional  supported
  859.         precompiler  defines  are  '__TIMESTAMP__',  '__BASE_FILE__'  and
  860.         '__INCLUDE_LEVEL__'.   A  list  of  the  predefined  preprocessor
  861.         defines for the supported compiler types is shown in  appendix  1
  862.         together  with  tips  for  the  adaptation  of  other  compilers.
  863.         Features like  the  replacing  of  trigraphs,  digraphs  and  the
  864.         recognition  of  C++  comments  '//...'  are  also treated by the
  865.         preprocessor.
  866.  
  867.         The precompiler recognises several errors or possible sources for
  868.         problems like
  869.  
  870.         -    the use of undefined variables in precompiler controls,
  871.         -    misbalanced '#if...' control block(s)  including  the  exact
  872.              location (file, line) where the failing block started,
  873.         -    recursive called include files,
  874.         -    nested include files,
  875.         -    wrong number of macro arguments
  876.  
  877.         and displays diagnostic messages with an exact description of the
  878.         error or warning reason and its location in the source file.
  879.  
  880.  
  881.         4.2  C++ LANGUAGE IMPLEMENTATION
  882.  
  883.         For  the  description  of  the related C++ language standards and
  884.         other  literature  see  the  chapter   about   the   C   language
  885.         implementation.
  886.  
  887.         Although  CFT and CST were initially not developed to process C++
  888.         code it is possible  to  do  so.  In  that  case,  however,  some
  889.         restrictions and limitations should be considered.
  890.  
  891.         Data  type  modifiers  like  'far'  may  confuse the CST analysis
  892.         process. The recognition of C++ classes by CST is limited because
  893.         the handling of the internal class structure items (variables and
  894.         functions) is too complex to fit in the CST program.  So  classes
  895.         are only referenced by name but their internal structure will not
  896.         be scanned and displayed. The C++ class inheritance relationships
  897.         are  recognised  and  shown  in  a  class hierarchy graph listing
  898.         (option -b).  Structures in C++ with function names as  structure
  899.         members will not be processed correctly, function bodies inside a
  900.         structure   definition  may  cause  errors.   Templates  are  not
  901.         supported and will not be recognised.
  902.  
  903.         Calling member functions will not be recognised correctly due  to
  904.         missing class name and namescope resolving, this leads also to an
  905.         incomplete  call tree and a lot of warnings during analysis.  The
  906.         use of  overloaded  functions  with  equal  names  but  different
  907.         parameters   in  C++  programs  may  lead  to  incorrect  calling
  908.         relationships.  A variable initialization with parameters will be
  909.         misinterpreted  as  a function call.  A correct handling of these
  910.         and other C++  features  requires  a  complete  C++  source  code
  911.         analyser  to  keep track of the class functions belong to and the
  912.         different calling parameters.
  913.  
  914.  
  915.                                      - 15 -
  916.  
  917.  
  918.  
  919.         If precise information about C++ code is needed,  utilities  like
  920.         'class hierarchy browsers' or 'class viewers',  which are usually
  921.         part of C++ compiler environments, should be used instead.
  922.  
  923.         Because of the above described reasons, some care should be taken
  924.         if C++ code is processed and displayed.
  925.  
  926.  
  927.         4.3  DBASE SOURCE CODE
  928.  
  929.         DFT can process source code which is based on  the  DBASE  III/IV
  930.         programming language. This means that also source code written in
  931.         DBASE  derivatives  like CLIPPER (Summer '87) or probably FOXBASE
  932.         can be analysed.  The source code analyser tries to be as correct
  933.         as  possible  to  build  a  reliable hierarchy tree.  A function/
  934.         procedure  declaration  is  recognised  by  the  FUNCTION   resp.
  935.         PROCEDURE keyword. A function/procedure call is recognised by the
  936.         following statements:
  937.  
  938.              function()
  939.              CALL function
  940.              CALL function WITH parameters
  941.              DO function
  942.              DO function WITH parameters
  943.  
  944.         If  a  file  contains  no  function/  procedure declaration,  the
  945.         filename itself is taken as procedure name.  The  recognition  of
  946.         builtin functions/ procedures can be ignored (see option -E). All
  947.         tokens  are assumed case-insensitive and are internally converted
  948.         to upper-case characters.  System builtin functions/macros can be
  949.         specified by option -E. Include files (e.g. with CLIPPER) are not
  950.         processed.  The  Clipper 5 C/C++ style comments /*...*/ resp.  //
  951.         are (hopefully correct) recognized.
  952.  
  953.  
  954.         4.4  FORTRAN SOURCE CODE
  955.  
  956.         FFT can process source which is based on the FORTRAN 77 standard.
  957.         Each FORTRAN  line  is  divided  into  fields  for  the  required
  958.         information, each column represents a single character.
  959.  
  960.              COLUMN    FIELD
  961.                   1    comment indicator (C,c,*,!)
  962.                 1-5    label
  963.                   6    indicator for line continuation
  964.                7-72    statement field (standard is 72, extended to 132)
  965.  
  966.         FFT can process lines up to 132 columns,  however,  if characters
  967.         are found beyond column 72  a  warning  will  be  given  (can  be
  968.         disabled  with -NOWARN72).  Continuation lines  are merged before
  969.         they are analysed.  The number of continuation  lines  is  19  by
  970.         default  and can be varied between 0 and 99 (option -qn).  Inline
  971.         comments in the statement field start with '!',  the  text  until
  972.         end  of  line  is  ignored.  The standard intrinsic functions and
  973.         additionally  VAX-FORTRAN  intrinsic  functions  are  recognised.
  974.  
  975.  
  976.                                      - 16 -
  977.  
  978.  
  979.         Statement  functions  (comparable  to C preprocssor function-like
  980.         macros) are not recognised and may lead to 'undefined functions'.
  981.         Hollerith constants are not recognised and  handled.  All  tokens
  982.         are  assumed  case-insensitive  and  are  converted to upper-case
  983.         characters. Blanks are not significant and are not handled,  they
  984.         will  be removed (except inside character strings).  If option -I
  985.         is set,  INCLUDE statements are recognised    and  processed.  To
  986.         handle  this implementation dependent feature,  several different
  987.         types of include statements are accepted:
  988.  
  989.         C FORTRAN-LIKE SYNTAX, INCLUDE STATEMENT STARTS IN COLUMN 7
  990.               include-statement include-filename
  991.  
  992.         C C-LIKE SYNTAX, INCLUDE STATEMENT STARTS IN COLUMN 1
  993.         include-statement include-filename
  994.  
  995.         where include-statement is one of INCLUDE, #INCLUDE,  $INCLUDE or
  996.         %INCLUDE  and include-filename is one of 'filename',  "filename",
  997.         <filename> or  filename  (without  surrounding  characters).  See
  998.         option   -I   and  the  chapter  about  PROGRAM  LIMITATIONS  for
  999.         additional informations about file inclusion.
  1000.  
  1001.         The resulting function call graph may be  incorrect  due  to  the
  1002.         ENTRY  capability  of  FORTRAN  which  allows direct jumps into a
  1003.         function or subroutine body from the outside.  This may result in
  1004.         incorrect   relationships   for   the  ENTRY  statement  and  the
  1005.         surrounding function/subroutine.  The indirect call of  functions
  1006.         which  are given as formal parameters to subroutines or functions
  1007.         (comparable to pointers to functions  in  C)  are  not  correctly
  1008.         referenced.  Implicit  typing  for  function  definitions without
  1009.         return  type  will  not  be  recognised,  the  function  will  be
  1010.         displayed without a return type.
  1011.  
  1012.  
  1013.         4.5  LISP SOURCE CODE
  1014.  
  1015.         LFT  can process LISP and SCHEME source code.  The development of
  1016.         LFT was mainly based on the GNU-EMACS LISP dialect as it is  used
  1017.         in  the  GNU-EMACS macro extension language and its functionality
  1018.         was tested mainly with these macro files.  LISP  functions/macros
  1019.         are  recognised  by  the  DEFUN  and  DEFMACRO  keywords.  SCHEME
  1020.         functions are recognised by the DEFINE keyword, SCHEME processing
  1021.         is enabled by option -XSCHEME.  Unnamed functions  declared  with
  1022.         the   LAMBDA   keyword   can  be  recognised  optionally  (option
  1023.         -XLAMBDA).  Tokens  are  assumed  case-sensitive.   Comments  are
  1024.         recognised for ';' until end-of-line and between '#|' and '|#' as
  1025.         multi line comment blocks.
  1026.  
  1027.         The  source  code  analysis is performed in two passes: The first
  1028.         pass detects function/macro  declarations  and  the  second  pass
  1029.         analyses  the relationships.  Function calls via (funcall <fcn>),
  1030.         (function  <fcn>),  (apply  <fcn>),   (mapc  <fcn>)  and  similar
  1031.         constructs   may   not   be  correctly  evaluated  if  fcn  is  a
  1032.         function-symbol (e.g.  given as a function parameter) and  not  a
  1033.         valid  function  name.  System  builtin  functions/macros  can be
  1034.         specified by option -E.
  1035.  
  1036.  
  1037.                                      - 17 -
  1038.  
  1039.  
  1040.  
  1041.         LFT was designed to work with different types of LISP source code
  1042.         (as there are XLISP,  CLOS,  GNU-EMACS LISP,  ...),  although the
  1043.         large number of dialects may lead sometimes to problems.
  1044.  
  1045.  
  1046.         4.6  ASSEMBLER SOURCE CODE
  1047.  
  1048.         As  an  additional  feature,  CFT  and  FFT can process assembler
  1049.         source code for the Intel 80x86 processors (MASM 5.1,  TASM)  and
  1050.         for the Intel 80960 RISC processors (or any other "AT&T UNIX-like
  1051.         assembler"   like   GNU)   to  get  information  about  assembler
  1052.         procedures and functions being called from the  assembler  source
  1053.         files. This feature is useful for mixed language programming. The
  1054.         assembler  source  code scanner also detects and handles calls of
  1055.         include files.  The processing of assembler macros,  however,  is
  1056.         not  supported,  the  preprocessing  option  (-P) works only on C
  1057.         source code.  Assembler source files are recognised by their file
  1058.         extensions '.ASM' and '.S', there is no other way to force a file
  1059.         being processed as an assembler file.
  1060.  
  1061.         The  following  naming  convention  is used: For '.ASM' assembler
  1062.         files (MASM,  TASM) all identifiers are treated  case-insensitive
  1063.         and  will  be  transformed to lower (CFT) resp.  upper (FFT) case
  1064.         characters,  but identifiers in '.S' (GNU,  I960) assembler files
  1065.         are  treated  case-sensitive.   This  means,  that  an  assembler
  1066.         function 'func1' defined in an '.ASM' file can be called from the
  1067.         source by 'func1', 'FUNC1',  'Func1' or any other lower and upper
  1068.         case  character  combination.  If  'func1'  is defined in an '.S'
  1069.         file,  the name must match exactly.  The first leading underscore
  1070.         of  a  function name will be removed to get exact naming matches.
  1071.         Type modifiers in C source code like 'cdecl' or 'pascal' will not
  1072.         be considered.  Remember these  conventions  when  processing  C,
  1073.         FORTRAN and assembler files.
  1074.  
  1075.         Assembler code statements (inline code) inside C source code will
  1076.         not be processed and will be skipped, because it is too difficult
  1077.         to  handle  the several kinds of syntax being used for this  like
  1078.         'asm ...',  'asm "..."' or 'asm(...)' and the different  keywords
  1079.         ('asm', '_asm', '__asm', '__asm__', ...) used by various compiler
  1080.         implementations.
  1081.  
  1082.  
  1083.  
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.                                      - 18 -
  1099.  
  1100.  
  1101.         5    DATABASE GENERATION
  1102.  
  1103.         One  of  the  most  important features is the database generation
  1104.         which can be enabled with the -G option.  It is  performed  after
  1105.         writing  the  output  file  to  save  all  information  about the
  1106.         processed files in a  set  of  dBASE  compatible  database  files
  1107.         (extension  '.DBF')  for later use.  These database files contain
  1108.         all necessary information like function or data type  names,  the
  1109.         location   where   they   are   defined,    their   caller/callee
  1110.         relationship,  all  scanned  files  with  statistic  information,
  1111.         include files and so on. It was tried to store the information in
  1112.         the  most  compact  and effective database structure to save disk
  1113.         space.  Note that if  the  contents  of  the  database  files  is
  1114.         manipulated  by external tools like dBASE or something else,  the
  1115.         internal consistency will be corrupted and  wrong  or  unexpected
  1116.         results will happen!
  1117.  
  1118.         The  database  can be used to recall information,  for example to
  1119.         find out,  if and in which file and  on  which  line  a  specific
  1120.         function or data type is defined. A previously generated database
  1121.         can  be  read into CFT and CST (option -g) to add new files to it
  1122.         and/or to produce another  output  file  with  new  configuration
  1123.         options,  for  example  with the reverse call tree or only with a
  1124.         special selected item  of  interest  to  be  displayed.  Such  an
  1125.         incremental  database generation is also useful if large projects
  1126.         can be divided into a set of  commonly  used  files  and  project
  1127.         specific  files.  A  good example for this is the GNU C compiler,
  1128.         which consists of a set of language independent files  and  three
  1129.         language  dependent  file  sets  for C,  C++ and Objective-C.  To
  1130.         analyse this software with CFT or CST,  the language  independent
  1131.         part  can be stored into a database which is later reused for the
  1132.         language  dependent  parts  to  build   the   complete   set   of
  1133.         information.
  1134.  
  1135.         Note:  There  is  currently no possibility to update the analysis
  1136.         results for files which are already  in  the  database  and  have
  1137.         changed afterwards.  During database reading the user is informed
  1138.         about source files which are newer  than  that  being  previously
  1139.         analysed.  So  it is only possible to add files but not to update
  1140.         results.
  1141.  
  1142.         The ability to retrieve information about the  sources  from  the
  1143.         database  is  quite  useful in many cases.  Recalling information
  1144.         from a database is much faster than processing  all  the  sources
  1145.         again to find a specific item of interest.  The documentation and
  1146.         maintenance of large software projects is much more effective and
  1147.         easier to do if the developer has a tool to navigate through  the
  1148.         source  code  and  that  helps  him  in  his comprehension of the
  1149.         program and its internal structure. It is also useful for reverse
  1150.         engineering of source code to get an  overview  of  the  internal
  1151.         program structure.  Together with user programmable editors it is
  1152.         possible to offer the user a source code browser with a hypertext
  1153.         like feeling by integrating database recalling functions into the
  1154.         editors.
  1155.  
  1156.  
  1157.  
  1158.  
  1159.                                      - 19 -
  1160.  
  1161.  
  1162.         Additional utility programs,  called CFTN and CSTN (for  CFT  and
  1163.         CST),  which  can be used to retrieve information from databases,
  1164.         are available with supporting macros for their  integration  into
  1165.         the  BRIEF,  QEDIT  or MicroEMACS editor,  which are described in
  1166.         another section later in this manual.  The SXT  windows  versions
  1167.         provide an interface to the databases with DLL's.
  1168.  
  1169.  
  1170.  
  1171.  
  1172.  
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.  
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.  
  1194.  
  1195.  
  1196.  
  1197.  
  1198.  
  1199.  
  1200.  
  1201.  
  1202.  
  1203.  
  1204.  
  1205.  
  1206.  
  1207.  
  1208.  
  1209.  
  1210.  
  1211.  
  1212.  
  1213.  
  1214.  
  1215.  
  1216.  
  1217.  
  1218.  
  1219.  
  1220.                                      - 20 -
  1221.  
  1222.  
  1223.         6    PROGRAM LIMITATIONS
  1224.  
  1225.         First  of  all,  CFT  and CST (and the other SXT programs) cannot
  1226.         replace a compiler or a syntax checker like 'LINT' (for C/C++) to
  1227.         detect errors in the source code.  This means that it  should  be
  1228.         possible  to  compile the source code without fatal errors before
  1229.         it is possible to analyse it,  otherwise the  processing  results
  1230.         may be incorrect (and may be the system crashes ...).
  1231.  
  1232.         However,  there  are  some  situations  where  CFT and CST can be
  1233.         useful to detect bugs and inconsistencies in the source code like
  1234.  
  1235.         -    multiple definitions of functions or data types,
  1236.         -    different function return types,
  1237.         -    implicit declared functions with no prototype,
  1238.         -    function definitions used as prototype,
  1239.         -    recursive,  nested,  hidden and frequent  calls  of  include
  1240.              files,
  1241.         -    unterminated strings or character constants,
  1242.         -    nested comments,
  1243.         -    unterminated comments at end of file,
  1244.         -    misbalanced braces,
  1245.         -    unexpected end-of-file characters inside files,
  1246.         -    illegal characters in the source code,
  1247.         -    wrong number of macro arguments,
  1248.         -    missing macro arguments,
  1249.         -    misbalanced '#if...' control blocks.
  1250.  
  1251.         These  code  checks  are  done  on  multiple  files  in  multiple
  1252.         directories so that inconsistencies between different  files  can
  1253.         be  found and displayed.  This is a capability which conventional
  1254.         compilers working only on a single file at a time cannot  provide
  1255.         and will miss therefore (maybe the linker will find some of these
  1256.         inconsistencies).
  1257.  
  1258.         Some  statistical  information  about  the source code may not be
  1259.         correct if  preprocessing  is  enabled  (-P).  This  affects  all
  1260.         options which do statistics like the -p or -s option. The size of
  1261.         the  'pure' source code may not be correct due to macro expansion
  1262.         or removing of unnecessary blanks.  However,  the  file  size  is
  1263.         always correct because it will be taken from the source file.
  1264.  
  1265.         Most  of  the  program  limitations  are  caused  by  the limited
  1266.         available memory.  This means that  the  more  conventional  main
  1267.         memory you have,  the better it is. The real mode versions of CFT
  1268.         and CST do not use expanded or extended memory, no virtual memory
  1269.         management or disk  file  swapping,  so  keep  your  conventional
  1270.         memory  free of memory consuming TSR programs and other utilities
  1271.         if you want to process a  large  number  of  files.  The  use  of
  1272.         operating  systems  like  MS-DOS  6.0 and/or memory managers like
  1273.         EMM386,  QEMM or 386MAX to get more free conventional memory  may
  1274.         help to handle big applications with a large number of files.  If
  1275.         memory problems still occur during processing,  there is an  easy
  1276.         way  to  break  the  memory limits: use the 32 bit protected mode
  1277.         versions of CFT and CST, called CFT386 and CST386. These programs
  1278.         are running  in  protected  mode  and  so  they  have  no  memory
  1279.  
  1280.  
  1281.                                      - 21 -
  1282.  
  1283.  
  1284.         limitations  and are faster than the real mode versions.  You can
  1285.         also use the Windows 3.1,  Win32s,  Windows-NT and OS/2  versions
  1286.         which have also no memory limitations.
  1287.  
  1288.         The  number  and  the  sizes  of  files to be processed is nearly
  1289.         unlimited with 2^14 files and 2^31  bytes  maximum  file  length.
  1290.         Each  file can have 2^16 lines.  The number of functions and data
  1291.         types being handled is limited to 2^14.  These values  are  given
  1292.         for  the real mode versions,  the protected mode versions usually
  1293.         exceed them.  These limitations should be  enough  even  for  the
  1294.         biggest project that could be mentioned.
  1295.  
  1296.         The  ISO/ANSI C minimum requirement for include file nesting is 8
  1297.         levels,  this will be fulfilled  by  CFT  and  CST.  The  maximum
  1298.         include  file  nesting  level  is  limited by the number of files
  1299.         (streams) which can be opened simultaneously by one program. This
  1300.         is a compiler specific limit  usually  coming  from  the  library
  1301.         startup  code.  The  number of open files (streams) is defined by
  1302.         the  macro  FOPEN_MAX  in  the  include  file  'stdio.h'.  During
  1303.         preprocessing  the  number  of  nested files is usually less than
  1304.         FOPEN_MAX because  several  streams  are  already  used  for  the
  1305.         default I/O (stdin,  stdout,  stderr,  stdaux,  stdprn). Also the
  1306.         preprocessor needs  additional  streams  besides  those  for  the
  1307.         source  and  include  files:  One stream for the temporary output
  1308.         file,  one for a log-file (if option -L is set)  and  one  for  a
  1309.         filelist  file  (if this is declared on the command line with @).
  1310.         The maximum number of files being opened  simultaneously  differs
  1311.         for  the  various SXT program versions due to the built-in limits
  1312.         of the different compilers used to produce them. All SXT programs
  1313.         which process include files (CFT,  CST,  FFT) should be  able  to
  1314.         handle  at  least 10 nesting levels.  The message for the include
  1315.         file open error is 'too many open files'.
  1316.  
  1317.         The integrated C-preprocessor limits the size of expanded  macros
  1318.         to  6  Kbytes.  The  number  of  macros simultaneously defined is
  1319.         unlimited (ISO/ANSI: 1024) and only  affected  by  the  available
  1320.         memory.   The  number  of  macro  parameters  is  limited  to  31
  1321.         (ISO/ANSI: 31) and there are  up  to  31  significant  characters
  1322.         (ISO/ANSI:  31)  recognised.  The conditional compilation nesting
  1323.         levels of '#if ...  #endif'  control  blocks  is  limited  to  32
  1324.         (ISO/ANSI: 8).
  1325.  
  1326.         The  line  length is unlimited (ISO/ANSI: logical (?) line length
  1327.         is  509  characters).  The  number  of  characters  in  a  string
  1328.         (including  '\0') is 2048 (ISO/ANSI: 509).  The number of members
  1329.         in one structure/union is unlimited (ISO/ANSI: 127),  the  number
  1330.         of structure/union nesting levels is unlimited (ISO/ANSI: 15).
  1331.  
  1332.         The  recognition  of C/C++ identifiers like function and variable
  1333.         names follows the standard rules: an identifier consists of upper
  1334.         and lower case letters (A-Z,  a-z),  underscore  (_)  and  digits
  1335.         (0-9),  additionally  the  dollar  sign  ($)  will  be  accepted.
  1336.         National character set extensions as they are usual for languages
  1337.         in european countries like Germany,  Denmark  or  Sweden  can  be
  1338.         defined with option -J.
  1339.  
  1340.  
  1341.  
  1342.                                      - 22 -
  1343.  
  1344.  
  1345.         C++  comments  '//...' are usually only recognised if option -C++
  1346.         is set.  However,  to accept the non-standard extension  of  some
  1347.         compilers which allow such comments also in C source code, option
  1348.         -// can be used therefore.  Nested C style comments '/*...*/' are
  1349.         not allowed and will always produce warnings.
  1350.  
  1351.         CFT and CST may produce  warnings  with  wrong  line  numbers  if
  1352.         preprocessing  is  enabled  (option -P) and if the warning occurs
  1353.         inside a comment.  The reason is that line number synchronisation
  1354.         with '#line ...' is only guaranteed for executable source but not
  1355.         for  comments.  In  such  a  situation  the source code should be
  1356.         processed without  -P  to  get  the  correct  line  number  (such
  1357.         warnings are usually related to unexpected characters).
  1358.  
  1359.         The use of explicit preprocessor #line directives in C/C++ source
  1360.         leads  to  different results for the 'logical' (synchronised with
  1361.         #line) and physical file  line  numbers.  CFT  and  CST  use  the
  1362.         'logical' line numbers and therefore moving inside a file with an
  1363.         editor to a specific line may fail.
  1364.  
  1365.         The  calculation  depth  of  the  critical  function call path or
  1366.         structure nesting level  is  unlimited.  The  calculation  is  an
  1367.         extremely    recursive function and was successfully tested up to
  1368.         more than 100 nesting levels.  It is not known from which nesting
  1369.         level on a stack overflow will happen.
  1370.  
  1371.         CFT  cannot recognise and reference a function if it is used with
  1372.         its pure name without parentheses.  This happens  if  a  function
  1373.         name  is  assigned  to  a  function pointer variable or used as a
  1374.         function pointer argument in a function call. Indirect calls to a
  1375.         function via a function pointer cannot  be  resolved.  A  similar
  1376.         case  with  FFT is the use of function names as formal parameters
  1377.         and their use within subroutines or functions.
  1378.  
  1379.         CFT will be confused in some rare cases by extensive type-casting
  1380.         operations like 'void __based(void) * __cdecl ...  ()'  and  will
  1381.         display  unexpected  messages.  A  function prototype declaration
  1382.         inside a function block ('function  given  scope')  will  not  be
  1383.         recognised by CFT as a prototype declaration,  instead it will be
  1384.         misunderstanded as a function call.  In  assembler  source  code,
  1385.         some  definitions of local variables seem to look like a function
  1386.         or a label definition and are treated by CFT like  that  although
  1387.         this  may be wrong in some cases.  It is also not always possible
  1388.         to detect a call  of  a  local  label  correctly.  CFT  sometimes
  1389.         displays  warning  messages  about  'return type mismatch' though
  1390.         this may be correct in that special case  because  the  different
  1391.         types are earlier defined by a 'typedef' declaration.  The reason
  1392.         is simply that CFT doesn't recognise these  'typedef's  (but  CST
  1393.         does!), it looks only for function names.
  1394.  
  1395.         An  often  requested  feature  for  CST is the integration of the
  1396.         calculation of structure/union sizes with byte offset information
  1397.         for every structure/union member. This feature is not implemented
  1398.         in CST although it would be  possible  to  do  this  because  all
  1399.         necessary information are present. The reason is that there would
  1400.         be  too  much  overhead  for  CST  to  treat the various compiler
  1401.  
  1402.  
  1403.                                      - 23 -
  1404.  
  1405.  
  1406.         implementations   with   their   different   basic   type   sizes
  1407.         (sizeof(int),  sizeof(long double)) for different processor types
  1408.         (16  bit,  32  bit,   64  bit,   ...)  and  data  type  alignment
  1409.         requirements  (by default and also controlled with #pragma's like
  1410.         'align' or 'pack').  It would be possible to do this for just one
  1411.         selected  compiler implementation or processor type but not for a
  1412.         great  number  of  them.   Especially  compilers   for   advanced
  1413.         architectures  like  RISC  processors  have very complicated type
  1414.         alignments rules depending on the data types,  alignment pragmas,
  1415.         compiler  switches,  type  sizes,  available  register number and
  1416.         register  sizes  and  resulting  structure/union/class  sizes  to
  1417.         generate  highly  optimised  code.   This  includes  usually  the
  1418.         insertion of 'fill' bytes inside a structure/union and  sometimes
  1419.         'padding  bytes' at the end of a structure/union to force aligned
  1420.         sizes on specific byte boundaries (For examples see the reference
  1421.         manual of the Intel 80960 C-Compiler iC960, release 3.0). Because
  1422.         of these reasons,  an integrated 'byte offset calculation' is not
  1423.         implemented in CST.  Instead,  you can generate a source file for
  1424.         selected  data  types  with  option  -O,   that  performs   these
  1425.         calculations,  if  you  compile  the  generated  file with your C
  1426.         compiler.  For further information see the description for option
  1427.         -O.
  1428.  
  1429.         Option  -z  in  combination  with  option  -I  produces redundant
  1430.         results with CFT,  CST and FFT if files with executable code  (or
  1431.         something that can be interpreted as that,  e.g.  function calls,
  1432.         data types or COMMON  blocks)  are  included  directly  inside  a
  1433.         function or data type block. (Especially in FORTRAN this seems to
  1434.         be  common  practice  to  include COMMON blocks into function and
  1435.         subroutine bodies.) For CFT and CST (but not for  FFT)  also  the
  1436.         call  tree references will be incomplete and therefore incorrect.
  1437.         With option -P for CFT and CST everything works fine, because the
  1438.         preprocessor works more precise  as  the  simple  file  inclusion
  1439.         mechanism option -I uses.
  1440.  
  1441.         SUMMARY
  1442.  
  1443.         The  above  described  limitations can lead in some situations to
  1444.         misinterpretations or loss of information of the  scanned  source
  1445.         code. The only way to avoid these lacks would be the inclusion of
  1446.         parts of a 'real compiler' to handle the complete language syntax
  1447.         in  any  possible situation.  But this was not the intention when
  1448.         the development of these programs as 'little'  and  easy  to  use
  1449.         general  purpose  programming supporting tools began.  Although I
  1450.         hope that the SXT programs will in most  cases  be  powerful  and
  1451.         useful development and documentation tools!
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.  
  1460.  
  1461.  
  1462.  
  1463.  
  1464.                                      - 24 -
  1465.  
  1466.  
  1467.         7    SXT OPTIONS
  1468.  
  1469.         This  section gives a complete overview about all SXT options and
  1470.         their syntax.  It gives also remarks  for  their  use  and  shows
  1471.         several  examples  with  detailed  descriptions.  The options are
  1472.         case-sensitive!  There are no differences between the  real  mode
  1473.         and  the  other  versions  of  the  SXT programs.  In the Windows
  1474.         versions,  all options can be set both on the command line and by
  1475.         menu  selections  and  dialog  windows.  For every option the SXT
  1476.         programs which support it are listed in parentheses.
  1477.  
  1478.         This section of the documentation should be read very careful  by
  1479.         all users to get a complete overview about all the features which
  1480.         are provided.
  1481.  
  1482.         THE OPTIONS ARE LISTED IN LEXICOGRAPHICAL ORDER.
  1483.         NONE OF THE OPTIONS IS SET BY DEFAULT.
  1484.  
  1485.         SYNTAX:   CFT [options [$cmdfile]] <[+]file> <@filelist>
  1486.                   CST [options [$cmdfile]] <[+]file> <@filelist>
  1487.                   DFT [options [$cmdfile]] <[+]file> <@filelist>
  1488.                   FFT [options [$cmdfile]] <[+]file> <@filelist>
  1489.                   LFT [options [$cmdfile]] <[+]file> <@filelist>
  1490.  
  1491.  
  1492.         OPTIONS:       (valid for SXT program)
  1493.  
  1494.  
  1495.         -Bsizes        (CFT, CST)
  1496.         Redefine  the basic type sizes and pointer type sizes (all values
  1497.         must be declared in bytes) for conditional preprocessor  controls
  1498.         with  the  'sizeof()'  keyword like '#if sizeof(int) == 4'.  This
  1499.         option is only valid with the -P option.
  1500.  
  1501.         The required format for this option is
  1502.  
  1503.              -Bv,c,s,i,l,f,d,ld*data,code
  1504.                                |
  1505.              (delimiter between data and pointer sizes is '*')
  1506.  
  1507.         with the following types and their respective default  data  size
  1508.         values in bytes (the pointer type sizes are model dependent):
  1509.  
  1510.         v    :    void (sizeof(void) is usually 0, but for GNU-C it is 1)
  1511.         c    :    char (1 byte)
  1512.         s    :    short (by definition 2 bytes, hardware independent)
  1513.         i    :    integer (hardware dependent, 2 or 4 bytes)
  1514.         l    :    long (4 bytes)
  1515.         f    :    float (4 bytes, IEEE format)
  1516.         d    :    double (8 bytes, IEEE format)
  1517.         ld   :    long  double  (10  bytes,  IEEE format,  some compilers
  1518.                   assume long double == double (= 8  bytes),  some  CPU's
  1519.                   and their compilers have special alignment requirements
  1520.                   like  the Intel 80960,  where sizeof(long double) is 16
  1521.                   bytes due to register and  memory  access  requirements
  1522.                   and structure alignment)
  1523.  
  1524.  
  1525.                                      - 25 -
  1526.  
  1527.  
  1528.         data :    data pointer (type pointers, 2 or 4 bytes, memory model
  1529.                   dependent)
  1530.         code :    code pointer (function pointers,  2 or 4 bytes,  memory
  1531.                   model dependent)
  1532.  
  1533.         The sizes of signed and unsigned types of the  same  basic  types
  1534.         are considered equal, this means that, for example, the following
  1535.         expression is true:
  1536.  
  1537.              sizeof(unsigned int) == sizeof(signed int) == sizeof(int)
  1538.  
  1539.         The  sizes of type pointers to data and function pointers to code
  1540.         are also considered equal,  this means  that,  for  example,  the
  1541.         following expressions are true:
  1542.  
  1543.              sizeof(int *) == sizeof(float *)
  1544.              sizeof(int (*)()) == sizeof(float (*)())
  1545.  
  1546.         A  64 bit (8 bytes) integer type like 'long long int' or 'bigint'
  1547.         (or something else) is  currently  not  supported  although  some
  1548.         (co-)processors  and  their assemblers are able to handle it (see
  1549.         Intel 80960 assembler manual for examples).  Also the  DEC  Alpha
  1550.         processor with its 64 bit architecture should support this.
  1551.  
  1552.         If  the -B option is not set,  the default values for the various
  1553.         memory models and compiler types (as they are known  to  me)  are
  1554.         used,   the   assumed   target   hardware   has  an  Intel  80x86
  1555.         microprocessor.  Note that during preprocessing type modificators
  1556.         like "near" or "far" are not recognised.
  1557.  
  1558.         If  the  -B  and  the  -T options are not set,  the sizes of data
  1559.         pointers and code pointers are always considered equal:
  1560.  
  1561.              sizeof(int *) == sizeof(int (*)())      (= 4, large model)
  1562.  
  1563.         For  example,   -B0,1,2,2,4,4,8,10*4,4  would  be   the   correct
  1564.         declaration  for  MS-C  7.0,  large/huge  memory model,  with the
  1565.         values for data types (void = 0,  char = 1,  short = 2,  int = 2,
  1566.         long = 4,  float = 4, double = 8 and  long double = 10 bytes) and
  1567.         pointers to data  types  and  function  pointers  (all  values  4
  1568.         bytes).  These values are set automatically by defining -TMSC70,L
  1569.         (or -TMSC70,H) as compiler type and memory model description  for
  1570.         preprocessing.
  1571.  
  1572.  
  1573.         -BATCH[inifile]     (SXT WINDOWS VERSIONS ONLY)
  1574.         This  command  line  option  can  only  be  used  with the SXTWIN
  1575.         programs.  It allows to start a SXTWIN program in batch mode  via
  1576.         the  'File'  'Run' menu or any other program.  The SXTWIN program
  1577.         executes the commands (from the command line and INI-file) and is
  1578.         closed  automatically  after  having   finished.   The   optional
  1579.         parameter     'inifile'     specifies     the    complete    name
  1580.         (drive:/dir/filename) of the INI-file that  should  be  used  for
  1581.         analysis.
  1582.  
  1583.  
  1584.  
  1585.  
  1586.                                      - 26 -
  1587.  
  1588.  
  1589.         -C++           (CFT, CST)
  1590.         Enable C++ source code processing.  This includes the handling of
  1591.         C++ comments '//...',  the recognition of C++  keywords  and  the
  1592.         definition of the macro name '__cplusplus' for preprocessing.  If
  1593.         a  supported  compiler  defines  additional  macro   names   like
  1594.         '__TCPLUSPLUS__'  for  Turbo-C  they  will also be defined before
  1595.         preprocessing.  Option -C++ is strictly required to  process  C++
  1596.         code correct.
  1597.  
  1598.  
  1599.         -CALL          (FFT)
  1600.         Recognise  and display only subroutine 'CALL ...' statements in a
  1601.         function or subroutine body.  In some cases this  option  can  be
  1602.         useful  if the source code scanner gets confused by indexed array
  1603.         accesses which might be misinterpreted as  function  calls.  With
  1604.         this option only the 'CALL ...' statements are detected.
  1605.  
  1606.  
  1607.         -CLIPPER       (DFT)
  1608.         Handle  CLIPPER  specific extensions: comments '//' and '/*...*/'
  1609.         and extended character set ':{}'.
  1610.  
  1611.  
  1612.         -COMMON        (FFT)
  1613.         Recognize and display COMMON  block  names.  The  block  name  is
  1614.         surrounded by '/' like /name/,  a blank COMMON block is named //.
  1615.         In the output file,  COMMON block names are handled like function
  1616.         names,  e.g.  the  call statistics says '# calls'.  Note that the
  1617.         BRIEF and MicroEMACS macros cannot handle block  names  correctly
  1618.         since they do not accept the '/' character.
  1619.  
  1620.  
  1621.         -CTAGS[x]      (CFT)
  1622.         This  option  generates a CTAGS file with information for VI-like
  1623.         tagging of defined identifiers. The CTAGS file is named "TAGS" by
  1624.         default unless the optional extension 'x'  is  used  to  specifiy
  1625.         another filename. Each entry in the TAGS file has the format
  1626.  
  1627.              identifier<tab>file<tab>vi-search-pattern
  1628.  
  1629.         where  'vi-search-pattern'  is  a regular expression matching the
  1630.         line  where  'identifier'  is  defined.   This  is  the   default
  1631.         implementation   for   CTAGS.   The  generated  TAGS  files  were
  1632.         successful tested with the MSDOS versions  of  VI  (from  Mortice
  1633.         Kern  Systems  Inc.)  and  the public domain VI-clone ELVIS,  but
  1634.         should also work with other VI versions. Since VI originates from
  1635.         UNIX, the TAGS file contains only LF, not CR+LF,  as line ending.
  1636.         I  have  done  it  this  way  to  avoid  possible  problems  with
  1637.         close-to-UNIX VI ports, but this may also lead to new problems if
  1638.         CR+LF is really needed.  To change from DOS to  UNIX  styles  and
  1639.         vice versa tools like DOS2UNIX or UNIX2DOS can be used.  See also
  1640.         option -TAGS for additional information.
  1641.  
  1642.         Note that  this  option  cannot  work  together  with  option  -P
  1643.         (preprocessing),  this  applies  also  to  results generated from
  1644.         databases previously created with option -P.  The reason is  that
  1645.  
  1646.  
  1647.                                      - 27 -
  1648.  
  1649.  
  1650.         the  preprocessed  source  does  usually  not correspond with the
  1651.         original  source,   it  contains  additional  #line   directives,
  1652.         comments  and  obsolete  blanks are removed,  fileoffsets are not
  1653.         valid.  Therefore the option -CTAGS can only  be  used  with  the
  1654.         original source code.
  1655.  
  1656.  
  1657.         -C[s]          (CFT, CST, DFT, FFT, LFT)
  1658.         List  the  function/data  type contents for every processed file,
  1659.         's' sorts by line numbers (DEFAULT ORDER: lexicographical). There
  1660.         are additional information possible with the option -s.  A remark
  1661.         is  given  if  none  of the functions defined in a file is called
  1662.         from functions defined in other files (internal  versus  external
  1663.         linkage). Functions for which no external caller outside the file
  1664.         is found will be marked [INTERNAL], such functions are candidates
  1665.         for defining them as 'static'. Attention: Calling a function by a
  1666.         function pointer won't be noticed!  This information is useful to
  1667.         find out whether the contents of a file is  unnecessary  for  the
  1668.         project  so  that the file must not be linked.  This option gives
  1669.         useful information about source code metrics  for  every  defined
  1670.         function.   Most   of   the   values  are  given  in  the  format
  1671.         "average [minimum ... maximum]".  Almost the same information are
  1672.         provided for data types with CST.
  1673.  
  1674.  
  1675.         -D[..]         (CFT, CST, DFT, FFT, LFT)
  1676.         Specifies  macro  name(s)  (-Dname or -Dname1=name2) or file with
  1677.         macro names (-D@namelist) of functions/data types which should be
  1678.         predefined and linked together,  also used as preprocessor define
  1679.         if the integrated preprocessor is called (-P).  The defined names
  1680.         are case  sensitive  and  trigraph  and  digraph  translation  is
  1681.         performed  on  them.  For preprocessing,  the -D option has lower
  1682.         precedence than the -U option. That is,  if the same name is used
  1683.         in  both a -U option and a -D option,  the name will be undefined
  1684.         regardless of the order of the options.
  1685.  
  1686.         The definition of a string as replacement for  a  macro  name  is
  1687.         different  on the command line and inside a macro definition file
  1688.         or command file (marked with  '$').  On  the  command  line,  the
  1689.         double  quotation  marks must be 'escaped' and the string must be
  1690.         quoted like '-DXYZ="\"123\""' (similar  to  C  strings)  to  work
  1691.         correctly,  the  reason  is  the  DOS  wildcard  expansion of the
  1692.         command line.  Inside a macro definition  or  command  file,  the
  1693.         double  quotation marks need not be 'escaped',  so the definition
  1694.         can be written like '-DXYZ="123"'.  This option cannot be used in
  1695.         environment  defines  if  the equal sign '=' is used because this
  1696.         produces a syntax error for DOS when trying to store a  'SET=...'
  1697.         command  with  a second equal sign in one line.  If a define item
  1698.         consists  of  two  words  see  the  notes  at  option  -S  for  a
  1699.         description.  Keep  these  differences  and exceptions in mind to
  1700.         avoid unexpected results using the -D option.
  1701.  
  1702.  
  1703.  
  1704.  
  1705.  
  1706.  
  1707.  
  1708.                                      - 28 -
  1709.  
  1710.  
  1711.         -Ename         (CFT, CST, FFT)
  1712.         Almost the same as -I, but the path for the include files will be
  1713.         taken from the  environment  variable  'name'.  Typing  -EINCLUDE
  1714.         would produce the same results as -I alone.
  1715.  
  1716.  
  1717.         -E[..]         (DFT, LFT)
  1718.         Specifies  name(s)  (-Ename)  or file with names (-E@namelist) of
  1719.         external or builtin functions. For LISP, this option is useful if
  1720.         GNU-Emacs Lisp source code is scanned to  reduce  the  number  of
  1721.         undefined  functions  listed  in  the  output  file.  A  list  of
  1722.         GNU-EMACS (version 18.59) builtin functions  is  given  with  the
  1723.         file GNULISP.FCT.  For DFT this option prevents output of builtin
  1724.         functions/  keywords.  An  example  file  with  DBASE  functions/
  1725.         procedures is provided with DBASE.FCT.
  1726.  
  1727.  
  1728.         -F             (CFT, CST, DFT, FFT, LFT)
  1729.         Use  only ASCII characters for the calltree output instead of the
  1730.         DEFAULT semigraphic characters.  This option  is  useful  if  the
  1731.         generated  output  file should be printed on a printer which does
  1732.         not support semigraphic characters like they are defined  in  the
  1733.         IBM character set. It can also be used to prepare the output file
  1734.         for  use  in a WINDOWS application like MicroEMACS if there is no
  1735.         font with semigraphics available.
  1736.  
  1737.  
  1738.         -G[name]       (CFT, CST, DFT, FFT, LFT)
  1739.         Generate a database with the complete set  of  information  about
  1740.         the processed sources.  The additional parameter 'name' (path and
  1741.         filename) is used as an unique base name for the set of  database
  1742.         files  (up  to  6  significant characters),  the DEFAULT SXT NAME
  1743.         ('CXT',  'DXT',  ...) is used if no name is specified.  If 'name'
  1744.         ends with a (back-)slash, it is used as a pathname. The generated
  1745.         database files (extension '.DBF') are dBASE compatible. There are
  1746.         two  additional files created,  one with the command line options
  1747.         (extension '.CMD') and one  with  a  list  of  the  source  files
  1748.         (extension '.SRC') being use for database generation. They can be
  1749.         used as command line definition files with '$' (command list) and
  1750.         '@' (file list).
  1751.  
  1752.         As  a result of the database generation you will find files named
  1753.         'CXTxy.ext' (or other SXT names) respectively 'namexy.ext'  (user
  1754.         defined 'name'),  where 'x' will be 'F' (function) for CFT,  DFT,
  1755.         FFT and LFT or 'S' (structure) for CST,  'y' is  replaced  by  an
  1756.         internally  used  character  to mark the different database files
  1757.         and their contents.
  1758.  
  1759.  
  1760.         -H[elp]        (CFT, CST, DFT, FFT, LFT)
  1761.         See option -?.
  1762.  
  1763.  
  1764.  
  1765.  
  1766.  
  1767.  
  1768.  
  1769.                                      - 29 -
  1770.  
  1771.  
  1772.         -HTML          (CFT, CST, DFT, FFT, LFT)
  1773.         This  option  generates  a  HTML  (HyperText   Markup   Language)
  1774.         compatible  calltree  output file and additional sorted item name
  1775.         and filename index files which can be viewed with  a  WWW  (World
  1776.         Wide  Web)  Browser like NCSA Mosaic,  Netscape or MS-WinWord 6.0
  1777.         Internet Assistant.  The HTML output is done in parallel with the
  1778.         '.LST'  output  file,  so all calltree options influence also the
  1779.         HTML output.  It is strictly recommended that option -r  is  set,
  1780.         otherwise no file information will be available.  The HTML output
  1781.         files are named "prog.HTM", "progNAMES.HTM",  "progFILES.HTM" and
  1782.         "progXREF.HTM"  (where  'prog' is one of CFT,  CST,  DFT,  FFT or
  1783.         LFT).  Because the HTML output  files  refer  to  each  other  by
  1784.         hypertext links there is no possibility to rename them. To handle
  1785.         multiple  sets of HTML output files copy each set into a separate
  1786.         directory.  To avoid unresolved  links  it  is  recommended  that
  1787.         options  -r -a (and -u,  if available) are set to ensure that all
  1788.         items are listed.  Note that  national  character  sets  are  not
  1789.         handled properly. For additional information see HTML_RTF.DOC.
  1790.  
  1791.         If  you  have  access to NCSA Mosaic or Netscape you can view the
  1792.         generated HTML output file with the builtin preview option  as  a
  1793.         local  file  and  use  the  hyperlinks  to  explore  the calltree
  1794.         relationships of the analysed source code (For  best  results  in
  1795.         viewing the calltree with a WWW client,  select a fixed-size font
  1796.         e.g.  Courier or Courier New).  The SXT-HTML features were tested
  1797.         with NCSA Mosaic for MS-Windows v2.0 beta 4, Netscape 1.1 (16bit)
  1798.         and MS-WinWord 6.0a Internet Assistant 1.0Z.  The HTML files were
  1799.         also  tested  with  Mosaic  and  Netscape  running   on   a   SUN
  1800.         workstation. The best results were achieved with Netscape on both
  1801.         platforms,  because  Mosaic  has problems with hypertext links in
  1802.         local files.  A copy of NCSA Mosaic can be  downloaded  with  FTP
  1803.         from 'ftp.ncsa.uiuc.edu', Netscape can be found at 'ftp.mcom.com'
  1804.         and   the  WinWord  6.0a  Internet  Assistant  can  be  found  at
  1805.         'ftp.microsoft.com'.
  1806.  
  1807.  
  1808.         -I[path]       (CFT, CST, FFT)
  1809.         This option enables the scanning of include files  declared  with
  1810.         '#include "..."' or '#include <...>' or with a similar syntax for
  1811.         FORTRAN.  The  required  path for the include files is taken from
  1812.         the INCLUDE environment variable (DEFAULT BEHAVIOUR)  or  can  be
  1813.         user  defined  by 'path'.  Paths defined with -I will be searched
  1814.         before any other paths taken from environment variables specified
  1815.         by -E or -P,  so care should be taken with that  option.  Include
  1816.         paths  can be given either absolute or relative.  A relative path
  1817.         is always considered relative to the directory of the source file
  1818.         it is used with,  not to the directory the  analysis  is  started
  1819.         from  or  the  analysis  program  is  located.  For preprocessing
  1820.         (option -P) declaring -I* ignores missing include files or errors
  1821.         with files which could not  be  opened  due  to  compiler  limits
  1822.         (message 'too many open files', see chapter PROGRAM LIMITATIONS).
  1823.         This  is  a  'quick  and  dirty'  approach,  but can sometimes be
  1824.         useful,  if include file locations are unknown  or  inaccessible.
  1825.         However, the results will not be absolutely correct.
  1826.  
  1827.  
  1828.  
  1829.  
  1830.                                      - 30 -
  1831.  
  1832.  
  1833.         Using  the  -I or -E option without -P allows the scanning of the
  1834.         source file and the included files without preprocessing. In that
  1835.         case an include file is handled as if  it  were  a  complete  new
  1836.         file,  this  can  lead to errors if a file inclusion is specified
  1837.         within a function or structure.  Also preprocessor controls  like
  1838.         '#if  ...'  are not evaluated and can lead to unexpected results.
  1839.         Remember this especially if you place  special  comment  sections
  1840.         enclosed in '#if 0 ... #endif' blocks.
  1841.  
  1842.  
  1843.         -Jcharset      (CFT, CST, DFT, FFT, LFT)
  1844.         Extend  the  DEFAULT  character for identifier recognition with a
  1845.         user defined character set  'charset'.  All  characters  must  be
  1846.         specified within one -J option.  The following default identifier
  1847.         character sets are used:
  1848.  
  1849.              C/C++     a-z A-Z 0-9 _$
  1850.              DBASE     a-z A-Z 0-9 _
  1851.              FORTRAN   a-z A-Z 0-9 _
  1852.                        a-z A-Z 0-9 _$                (with option -$)
  1853.              LISP      a-z A-Z 0-9 +-.*/<=>!?:$%_&~^
  1854.  
  1855.         This option allows the programmer to use national character  sets
  1856.         as they are common in Germany, Denmark, Sweden and other european
  1857.         countries.
  1858.  
  1859.  
  1860.         -L[L][+]       (CFT, CST, DFT, FFT, LFT)
  1861.         Redirect  the  screen  output  to a file,  called 'CFT.LOG' resp.
  1862.         'CST.LOG'.  If '+' is set,  the output is both written to  screen
  1863.         and  redirected  to  the log file so that the output messages can
  1864.         both be viewed as they appear and later  analysed.  Finally,  -LL
  1865.         resp.  -LL+ appends the output to an existing log-file,  this can
  1866.         be useful if CFT and CST are run from a batch-file to  catch  all
  1867.         output.
  1868.  
  1869.  
  1870.         -LIB[..]       (CFT)
  1871.         Specifies  name(s)  (-LIBname) or file with names (-LIB@namelist)
  1872.         of  library  functions.  Library  functions  are  not  listed  as
  1873.         undefined  functions  in  the  output  file.  Lists  of C-library
  1874.         functions are given with the files MSVC15.FCT (MS Visual C++ 1.5)
  1875.         and GCC233.FCT (GNU-C 2.3.3).
  1876.  
  1877.  
  1878.         -M             (CFT, CST, FFT)
  1879.         This option generates a source file/include file dependency table
  1880.         for every processed file.  This table shows the dependent include
  1881.         files  of  a  source file and can be used for a MAKE file.  It is
  1882.         also useful to check if the included files  are  taken  from  the
  1883.         correct  directories.  If a file is included more than once,  the
  1884.         number of inclusions will be displayed.  Note  that  this  option
  1885.         will only work correctly if options -P or -I are used, but not on
  1886.         preprocessed  files.  There  may  also  be  problems  with  files
  1887.         produced by source code generators like LEX/FLEX or YACC/BISON.
  1888.  
  1889.  
  1890.  
  1891.                                      - 31 -
  1892.  
  1893.  
  1894.  
  1895.         -N             (CFT, CST, DFT, FFT, LFT)
  1896.         Disable the writing of an output file.  This option can be useful
  1897.         if,  for example, only a database (option -G) should be generated
  1898.         with CFT or CST and no output file is required.  In that case the
  1899.         sometimes  very  time consuming process of output file writing is
  1900.         skipped.  Note that for CST the writing of the byte  offset  file
  1901.         "CST_OFFS.C" will not be affected by this option.
  1902.  
  1903.  
  1904.         -NODIGRAPH     (CFT, CST)
  1905.         Disable  digraph  translation  during preprocessing (options -P).
  1906.         This option can be useful for processing some Microsoft  specific
  1907.         code,  because  the Microsoft specific 'based-code' operator ':>'
  1908.         (introduced with MS-C 6.0) is also a digraph which translates  to
  1909.         ']'. This may lead in some situations to 'unbalanced brackets'.
  1910.  
  1911.  
  1912.         -NOINTR        (FFT)
  1913.         Do  not  recognise  and  display  INTRINSIC  functions  in output
  1914.         calltree.  Only subroutines and functions defined in  the  source
  1915.         code are displayed.
  1916.  
  1917.  
  1918.         -NOLIB         (CFT)
  1919.         Do  not  display  library  functions  defined with option -LIB in
  1920.         output calltree.
  1921.  
  1922.  
  1923.         -NOREPLACE     (CFT, CST)
  1924.         Disable C++ keyword replacing. This option can be useful if older
  1925.         C++ code with identifiers which are now  recognized  as  new  C++
  1926.         keywords is processed (e.g.  the keyword 'bitor' is replaced with
  1927.         '|').
  1928.  
  1929.  
  1930.         -NOUNSAFE      (CFT, CST)
  1931.         This  option  warns  in  case  of  errors  with  'unsafe'   macro
  1932.         expansions  of  the  integrated  preprocessor  (option  -P) which
  1933.         otherwise  would  abort  execution   with   fatal   errors   (see
  1934.         PROBLEMS.DOC).  This  is  only  a  'work-around' that can lead to
  1935.         following errors.
  1936.  
  1937.  
  1938.         -NOWARN72      (FFT)
  1939.         Do not warn if characters are found beyond  column  72.  FFT  can
  1940.         process  lines up to 132 columns length.  By default a warning is
  1941.         given if characters are found  beyond  column  72.  This  can  be
  1942.         disabled with this option.
  1943.  
  1944.  
  1945.         -O[..]         (CST)
  1946.         Specifies  name(s)  (-Oname)  or file with names (-O@namelist) of
  1947.         data types for which the  calculation  of  structure/union  sizes
  1948.         with byte offset information for every data type member should be
  1949.         performed.  Additionally  specifying  -O+  sets  a  flag  for the
  1950.  
  1951.  
  1952.                                      - 32 -
  1953.  
  1954.  
  1955.         recursive collection of sub-structures during expansion which are
  1956.         displayed without specifying them by -O.  This means  that  if  a
  1957.         structure/union  consists of members which are also structures or
  1958.         unions (and so on), it is not necessary to specify all these data
  1959.         type names with -O to enable them for  byte  offset  calculation.
  1960.         Instead,  you  have  to  specify only the top most data type with
  1961.         -Oname and additionally -O+ to force CST to  select  all  related
  1962.         sub-types  for  displaying.  If  -O+  is  set  but  NO  names are
  1963.         specified, ALL structures and unions will be used for byte offset
  1964.         calculations (the resulting file can be very big)!
  1965.  
  1966.         As the result of this option,  CST generates  a  C  source  file,
  1967.         called  'CST_OFFS.C'.  This file needs some additional editing to
  1968.         declare necessary include files,  data types,  defines or pragmas
  1969.         before  it can be compiled with the C compiler for which the file
  1970.         was generated (be sure to use the same includes!).  The resulting
  1971.         executable  prints  for  every  structure/union  member  the byte
  1972.         offset relative to the beginning of the structure/union  (decimal
  1973.         and  hexadecimal)  and  the  size  of each member,  the resulting
  1974.         structure/union   size   and   also   information    whether    a
  1975.         structure/union  member  has  been  aligned (= compiler dependent
  1976.         insertion  of  fill  bytes  before  that  member)   or   if   the
  1977.         structure/union  was  padded  with fill bytes at the end of it to
  1978.         align the size to a specific length.
  1979.  
  1980.         To  get  these  information  and   to   perform   the   necessary
  1981.         calculations  therefore,  the source file 'CST_OFFS.C' can become
  1982.         very large and makes use of the C macro programming capabilities,
  1983.         which  may  lead  in  some  rare  cases  to  errors  during   the
  1984.         compilation due to the internal limitations of some C compilers.
  1985.  
  1986.         The  -O  option  is  very useful if you need detailed information
  1987.         about structures/unions in case of error searching and debugging,
  1988.         especially for hardware debugging with an ICE.  It is also useful
  1989.         for  finding  out  the  differences  in  the internal layout of a
  1990.         structure/union in the case of  porting  C  source  code  between
  1991.         different   compilers   and/or   operating  systems  or  if  data
  1992.         structures are exchanged between  different  hardware  platforms,
  1993.         for  example  with  data  communication.  You  can  verify if the
  1994.         expected structure/union layout and size is  really  produced  by
  1995.         the target compiler.
  1996.  
  1997.  
  1998.         -P[name]       (CFT, CST)
  1999.         Run  the integrated C preprocessor before the file scan.  In this
  2000.         case the include path  is  taken  from  the  INCLUDE  environment
  2001.         variable  (DEFAULT  BEHAVIOUR),  from  the  user  defined  'name'
  2002.         environment and additional paths from -I and -E option are  used.
  2003.         If  special  paths  should  be searched before the default paths,
  2004.         they must be specified by the  -I  path  or  the  -E  environment
  2005.         option  and they must be placed on the command line before the -P
  2006.         option to be processed first. The -D, -U preprocessor defines and
  2007.         -T type and memory model and -B size  infos  are  also  used,  if
  2008.         defined.  The  path  for  the  preprocessor  output  file  can be
  2009.         specified  by  the  -v  option,  otherwise  the  current  working
  2010.         directory  will be used (DEFAULT BEHAVIOUR).  The comments in the
  2011.  
  2012.  
  2013.                                      - 33 -
  2014.  
  2015.  
  2016.         source and included files will remain  until  -q  is  defined  to
  2017.         remove them. The comments are used for statistics with option -p.
  2018.         If option -C++ is set, the macro '__cplusplus' will be predefined
  2019.         before  preprocessing  to  enable  C++  macros  and  C++  comment
  2020.         recognition.
  2021.  
  2022.         If a fatal error occurs during preprocessing, the analysis of the
  2023.         file will be aborted and the next  file  in  the  queue  will  be
  2024.         processed  (if  'out  of  memory' occurs the complete analysis is
  2025.         aborted!). For a description of the error format see option -W.
  2026.  
  2027.         If you are using a compiler which is not supported by CFT and CST
  2028.         or the build-in preprocessing doesn't satisfy your needs  because
  2029.         the results seem to be different from your preprocessor,  you can
  2030.         preprocess  the  files  you  want  to  analyse  with   your   own
  2031.         preprocessor  and  use  these files as input for CFT and CST.  To
  2032.         ensure that the filename and line  number  references  are  valid
  2033.         your preprocessor must insert #line directives into the source.
  2034.  
  2035.         Preprocessing  with another compiler can also be necessary if the
  2036.         integrated preprocessor  has  problems  with  your  source,  e.g.
  2037.         because  the  nesting  level  for  include files is too high (see
  2038.         section PROGRAM LIMITATIONS) or it aborts during macro expansions
  2039.         (see PROBLEMS.DOC).
  2040.  
  2041.  
  2042.         -Q[..]         (CFT, CST, DFT, FFT, LFT)
  2043.         Specify the name (-Qname) or a file with the names  (-Q@namelist)
  2044.         of those source files for which their functions/data types should
  2045.         be  listed  in the output calltree file (sorted by line numbers).
  2046.         The files are handled in the given -Q sequence.  If additional -S
  2047.         options  are specified,  the -S items will be listed after all -Q
  2048.         options are done.
  2049.  
  2050.  
  2051.         -R             (CFT, CST, DFT, FFT, LFT)
  2052.         By default,  CFT and CST generate the hierarchy tree chart of the
  2053.         called function/data type ("CALLER:CALLEE relation",  "WHO CALLES
  2054.         WHOM").  The -R option produces an inverted listing  showing  the
  2055.         callers/users of each function/data type. It generates the output
  2056.         as  the  function/data  type  hierarchy member list tree chart in
  2057.         reverse order as a list of calling items of the referenced  basic
  2058.         item  ("CALLEE:CALLER relation",  "WHO IS CALLED BY WHOM").  This
  2059.         option is useful to  get  the  relations  between  functions/data
  2060.         types and their callers/users.
  2061.  
  2062.  
  2063.         -RATIONAL      (CFT, CST, DFT, FFT, LFT)
  2064.         This  option  generates so called 'Petal' files for Rational Rose
  2065.         (Windows),  a  CASE-tool  supporting  the  Booch  Object-Oriented
  2066.         Analysis and Design (OOAD) method. The generated output files can
  2067.         be  imported by Rational Rose to use the builtin capabilities for
  2068.         visualisation,  but in the case of the SXT programs (mis-)used to
  2069.         graphically  visualize  the  calling  relationships  of functions
  2070.         resp. data types.   The -RATIONAL option is a work-around for the
  2071.  
  2072.  
  2073.  
  2074.                                      - 34 -
  2075.  
  2076.  
  2077.         missing  graphical layout capabilities of the SXT programs (which
  2078.         some users have requested in  the  past)  by  using  an  external
  2079.         program for doing the missing features.
  2080.  
  2081.         Two  different types of description files are generated,  one for
  2082.         class diagrams and one for finite state machine  (FSM)  diagrams.
  2083.         The class diagram files are named 'sxtprog.PTL' and the FSM files
  2084.         'sxtprog_FSM.PTL'  with  'sxtprog' as the name of the SXT program
  2085.         being  used.   CST   generates   two   additional   files   named
  2086.         'CSTCLASS.PTL'    and   'CSTCLFSM.PTL'   describing   the   class
  2087.         inheritance relationships in the same way. In the class diagrams,
  2088.         for functions (CFT, DFT, FFT, LFT) the USES-relationship was used
  2089.         to display the calling relationsships (the classes are misused as
  2090.         functions),    whereas   for   data   types   and   classes   the
  2091.         INHERITANCE-relationsship is used.
  2092.  
  2093.         If  you  have  Rational  Rose,  you have to perform the following
  2094.         steps to get impressive results: Start Rational  Rose,  select  a
  2095.         new  model ('File' - 'New') and import the generated file ('File'
  2096.         - 'Import...').  If you  imported  a  FSM  description,  a  class
  2097.         diagram  with  one  class symbol named 'CallGraph' (FSM) appears.
  2098.         Click on that symbol and choose 'Browse' - 'State  Diagram'.  Now
  2099.         select  'Tools'  -  'Layout'  to  start  the  layout optimization
  2100.         function.  As the result the graphical call tree  of  the  source
  2101.         code  analysis is displayed with each function/data type shown as
  2102.         a circle ('state') and the call relationship shown  as  an  arrow
  2103.         ('transaction') from the calling to the called item,  for classes
  2104.         from the superclass to  the  subclass.  You  can  zoom  into  the
  2105.         diagram,  print the results or incorporate the diagrams into your
  2106.         program documentation via Clipboard, e.g. into Word for Windows.
  2107.  
  2108.         In case of a class description file,  a class category  with  one
  2109.         category named 'Program' appears after file import.  Double click
  2110.         on that symbol to open the associated class diagram and  activate
  2111.         the layout function. As the result the graphical call tree of the
  2112.         source  code  analysis is displayed with each function shown as a
  2113.         class and the call relationship shown as a double line  from  the
  2114.         calling (circle) to the called function.
  2115.  
  2116.         NOTE:  The  SXT  programs cannot generate input for Rational Rose
  2117.         comparable to that generated by  the  C++  analyzer  of  Rational
  2118.         Rose, SXT just uses Rational Rose's printing capabilities!
  2119.  
  2120.         The -RATIONAL option was tested with the Beta version of Rational
  2121.         Rose/C++  (Windows)  2.0.  If  you get warnings reading the files
  2122.         with an earlier (later) version of Rational Rose  edit  the  file
  2123.         and reduce (increase) this value.  The SXT programs currently set
  2124.         this value 35 for version 2.5. Note that Rational Rose needs even
  2125.         for small and medium sized projects some time to import the  file
  2126.         and  process the diagram layout.  There is no guarantee that this
  2127.         will always be successful.
  2128.  
  2129.  
  2130.  
  2131.  
  2132.  
  2133.  
  2134.  
  2135.                                      - 35 -
  2136.  
  2137.  
  2138.         Rational Rose is  a  commercial  product,  for  more  information
  2139.         contact Rational directly at
  2140.  
  2141.              Rational,   2800  San  Tomas  Expressway,  Santa  Clara,  CA
  2142.              95051-0951, U.S.A.
  2143.  
  2144.              Rational GmbH, Rosenstr. 7, Grosshesselohe,  D-82049 Pullach
  2145.              im Isartal, Germany
  2146.  
  2147.  
  2148.         -RTF[x]        (CFT, CST, DFT, FFT, LFT)
  2149.         This  option  generates  a  RTF  (Rich  Text  Format)  compatible
  2150.         calltree and file contents list output file.  The RTF output file
  2151.         is named "prog.RTF" (where 'prog' is one of CFT, CST, DFT, FFT or
  2152.         LFT)  by  default  unless  the  optional extension 'x' is used to
  2153.         specifiy another filename.  The RTF output is  done  in  parallel
  2154.         with  the  '.LST' output file,  so all calltree options influence
  2155.         also the RTF output. It is strictly recommended that option -r is
  2156.         set,  otherwise no file information will be  available.  The  RTF
  2157.         file  can  be  imported  by  word processors which can handle RTF
  2158.         (e.g.  Word for Windows).  Another very  useful  feature  is  the
  2159.         possibilty  to  generate  a Windows Helpfile from the RTF output.
  2160.         This can be done by using the  Microsoft  Windows  Help  Compiler
  2161.         HC.EXE  resp.  HC31.EXE  (or  via  the  HC.BAT  batch file) which
  2162.         compiles the .RTF file into a  .HLP  file  (e.g.  'hc31  cft.rtf'
  2163.         generates cft.hlp).  The helpfile can be viewed with WINHELP.EXE.
  2164.         It contains a searchable sorted list  of  all  items  (functions,
  2165.         types),  a file contents list and a caller/callee cross reference
  2166.         list.  Similar to the HTML output,  hypertext links are  embedded
  2167.         which  allow  jumps  within the helpfile to item definitions.  To
  2168.         avoid unresolved links it is recommended that options -r -a  (and
  2169.         -u,  if  available)  are set to ensure that all items are listed.
  2170.         For additional information see HTML_RTF.DOC.
  2171.  
  2172.  
  2173.         -S[..]         (CFT, CST, DFT, FFT, LFT)
  2174.         Specify  name  (-Sname)  or  file  with  names  (-S@namelist)  of
  2175.         functions/data  types to search for and to dump if present (names
  2176.         are case sensitive).  Only these items are listed in  the  output
  2177.         calltree  file,  all others are ignored.  The items are listed in
  2178.         the given -S sequence. If also all the other items not covered by
  2179.         -S should be listed,  the user can specify  -S+  on  the  command
  2180.         line.  The '+' parameter forces all remaining items to be printed
  2181.         after all the -S items have been printed.  For DFT  and  FFT  the
  2182.         item  names are considered uppercase.  By using -S on the command
  2183.         line,  it is necessary to surround a data type name that consists
  2184.         of  two words with double quotation marks like "struct _iobuf" to
  2185.         connect the two words.  This is not necessary inside a list file,
  2186.         but there every search name must be on a separate line.
  2187.  
  2188.  
  2189.         -TAGS[x]       (CFT, CST, DFT, FFT, LFT)
  2190.         This  option  generates  a TAGS file with information for VI-like
  2191.         tagging of defined identifiers.  The TAGS file is named "TAGS" by
  2192.         default  unless  the  optional  extension 'x' is used to specifiy
  2193.         another filename. Each entry in the TAGS file has the format
  2194.  
  2195.  
  2196.                                      - 36 -
  2197.  
  2198.  
  2199.  
  2200.              identifier<tab>file<tab>vi-search-pattern
  2201.  
  2202.         where 'vi-search-pattern' is the  line  number  in  'file'  where
  2203.         'identifier'  is  defined.  As  using  the line number is a usual
  2204.         practice if 'typedef' definitions are included into the TAGS file
  2205.         this  should  be  no  problem.  The  generated  TAGS  files  were
  2206.         successful  tested  with  the  MSDOS versions of VI (from Mortice
  2207.         Kern Systems Inc.) and the  public  domain  VI-clone  ELVIS,  but
  2208.         should also work with other VI versions. Since VI originates from
  2209.         UNIX,  the TAGS file contains only LF, not CR+LF, as line ending.
  2210.         I  have  done  it  this  way  to  avoid  possible  problems  with
  2211.         close-to-UNIX VI ports, but this may also lead to new problems if
  2212.         CR+LF  is  really  needed.  To change from DOS to UNIX styles and
  2213.         vice versa tools like DOS2UNIX or UNIX2DOS can be used.  See also
  2214.         option -CTAGS for additional information.
  2215.  
  2216.  
  2217.         -Tn            (FFT)
  2218.         Set the tabulator expansion size to 'n' (DEFAULT: 8 characters).
  2219.  
  2220.  
  2221.         -Ttype,m       (CFT, CST)
  2222.         Use  this  option  to  set  the  compiler  type  for  source code
  2223.         preprocessing to one of the following types:
  2224.  
  2225.              MSC51     Microsoft C 5.1
  2226.              MSC70     Microsoft C/C++ 7.0
  2227.              MSVC15    Microsoft Visual C++ 1.5
  2228.              MSVCWNT   Microsoft Visual C++ 1.1 for Windows NT
  2229.              TC10      Borland Turbo C++ 1.0
  2230.              BC20      Borland C++ 2.0
  2231.              BC31      Borland C++ 3.1
  2232.              BC10OS2   Borland C++ 1.0 for OS/2
  2233.              GNU       GNU-C
  2234.              I960      Intel 80960 iC960 3.0
  2235.  
  2236.         The supported memory models are T(iny)  (valid  only  for  MSC70,
  2237.         MSVC15, TC10, BC20, BC31), S(mall), M(edium), C(ompact), L(arge),
  2238.         H(uge),  'L'  is assumed as default if no model is specified.  MS
  2239.         Visual C++ for Windows NT, Borland C++ for OS/2,  GNU-C and Intel
  2240.         iC960  do  not need a memory model because they compile really 32
  2241.         bit code. The Intel iC960 compiler requires the definition of the
  2242.         80960 RISC processor architecture which is one of KA, KB, SA, SB,
  2243.         MC, CA (default is KB).
  2244.  
  2245.         This option causes several compiler dependent preprocessor macros
  2246.         (if they  were  known  to  me,  however)  to  be  defined  before
  2247.         preprocessing  starts.  This  option can only be used with the -P
  2248.         option, otherwise it has no effect.
  2249.  
  2250.         If your compiler is not supported,  you can perform the following
  2251.         steps: Find out which preprocessor defines are necessary (manual,
  2252.         help  file)  and  declare  them  with  option  -D,  then declare,
  2253.         depending on the selected memory model or processor architecture,
  2254.         the type sizes with option -B.
  2255.  
  2256.  
  2257.                                      - 37 -
  2258.  
  2259.  
  2260.  
  2261.  
  2262.         -U[..]         (CFT, CST)
  2263.         Specifies  a  predefined  macro  name  (-Dname)  or   file   with
  2264.         predefined   macro   names  (-U@namelist)  to  be  undefined  for
  2265.         preprocessing.  Note that  the  default  predefined  macro  names
  2266.         '__FILE__',   '__LINE__',   '__DATE__',   '__TIME__'   cannot  be
  2267.         undefined.  All other predefined names for the  various  compiler
  2268.         types  can  be undefined.  Like for -D,  the names are considered
  2269.         case-sensitive,  but  trigraph  or  digraph  translation  is  not
  2270.         performed  because  the  internal  representation  cannot contain
  2271.         them.
  2272.  
  2273.  
  2274.         -V             (CFT)
  2275.         List prototyped functions which are neither  called  nor  defined
  2276.         (option -a and -u). This option is useful to find unused function
  2277.         prototypes which could be probably removed from the source code.
  2278.  
  2279.  
  2280.         -Wlevel        (CFT, CST, DFT, FFT, LFT)
  2281.         Set  error  and  warning  message  level.  Higher  warning levels
  2282.         include lower ones.  The DEFAULT  level  is  always  the  highest
  2283.         supported warning level, possible levels are:
  2284.  
  2285.         0 :  all  error  and warning messages are suppressed except fatal
  2286.              errors,
  2287.         1 :  display serious errors or warnings,
  2288.         2 :  includes level 1 plus additional errors and warnings,
  2289.         3 :  includes level 2 plus errors/warnings/remarks,
  2290.         4 :  includes level  3  plus  warnings  about  implicit  declared
  2291.              functions and lacks of type or storage class.
  2292.  
  2293.         The following levels affect only preprocessing (CFT and CST):
  2294.  
  2295.         5 :  includes   level   4   plus   warnings   and  errors  during
  2296.              preprocessing  (non-fatal   errors   and   warnings   during
  2297.              preprocessing  are otherwise not displayed,  preprocessor is
  2298.              running in 'silent mode'),
  2299.         6 :  includes  level  5  plus  remarks/slight   warnings   during
  2300.              preprocessing.
  2301.  
  2302.         The output format for messages during file scan is
  2303.  
  2304.              filename(line): error: description
  2305.              filename(line): warning: description
  2306.  
  2307.         and during preprocessing (warning levels 5 and 6)
  2308.  
  2309.              preprocessor: filename(line): error: description
  2310.                   source line
  2311.              preprocessor: filename(line): warning: description
  2312.                   source line
  2313.  
  2314.  
  2315.  
  2316.  
  2317.  
  2318.                                      - 38 -
  2319.  
  2320.  
  2321.         -X             (CFT, CST, DFT, FFT, LFT)
  2322.         Assume  a  UNIX-style  text  file:  no CR,  only LF.  The DEFAULT
  2323.         ASSUMPTION is  a  DOS-style  text  file  with  CR+LF.  Any  other
  2324.         combination like CR in UNIX-files,  CR without following LF or LF
  2325.         without preceding CR in DOS-files will cause a  warning  message.
  2326.         This  option  is  useful  to  detect  possible  conversion errors
  2327.         between  different  operating   systems   or   incorrect   editor
  2328.         configuration settings.
  2329.  
  2330.  
  2331.         -XLAMBDA       (LFT)
  2332.         Recognise  the  LISP  resp.  SCHEME  keyword 'lambda' for unnamed
  2333.         function declarations.  By DEFAULT,  'lambda'  is  treated  as  a
  2334.         simple identifier.
  2335.  
  2336.  
  2337.         -XSCHEME       (LFT)
  2338.         Assume  SCHEME source code instead of LISP source code (DEFAULT).
  2339.         This means that functions are recognised by the  'define'  SCHEME
  2340.         keyword instead of the 'defun' resp. 'defmacro' LISP keywords.
  2341.  
  2342.  
  2343.         -Y             (CFT, CST, DFT, FFT, LFT)
  2344.         Ignore  CR+LF  checks.  This option disables all checks which are
  2345.         done for unexpected CR+LF combinations in DOS or UNIX  files.  If
  2346.         option -Y is set,  option -X will be ignored.  This option can be
  2347.         useful if there would be too many messages concerning that  error
  2348.         or if this message would be of no interest for the user.
  2349.  
  2350.  
  2351.         -Z[s]          (CFT, CST, DFT, FFT, LFT)
  2352.         Display every caller and member for each function/data type,  's'
  2353.         sorts by the number of calls  (DEFAULT  ORDER:  lexicographical),
  2354.         this  is  an  extension  of the -c option.  This option shows the
  2355.         relations in the following form:
  2356.  
  2357.              List of parent functions/data types:
  2358.              1. caller (reference #) <# of calls from>
  2359.              ...
  2360.              n. caller ...
  2361.         function/data type (reference #) <# of calls from parents,  #  of
  2362.         calls to children>
  2363.              List of child functions/data types:
  2364.              1. called member (reference #) <# of calls to>
  2365.              ...
  2366.              m. called member ...
  2367.  
  2368.         This  compact  form lists all callers and members with the number
  2369.         of their calls, recursions are detected and displayed.  Note that
  2370.         this  option  can  be  extremely  time consuming if the number of
  2371.         source files is very large!
  2372.  
  2373.  
  2374.  
  2375.  
  2376.  
  2377.  
  2378.  
  2379.                                      - 39 -
  2380.  
  2381.  
  2382.         -a             (CFT, CST, DFT, FFT, LFT)
  2383.         List  every  function/data  type,   also  previously   referenced
  2384.         functions/data  types.  This  generates  a complete list of every
  2385.         function/data type in lexicographical order  with  references  to
  2386.         their first location.
  2387.  
  2388.  
  2389.         -b             (CST)
  2390.         Display  the  C++  class  inheritance relationships.  This option
  2391.         generates two listings.  The first one displays the complete  C++
  2392.         class  hierarchy  graph(s).  The  second one shows for each class
  2393.         first the superclasses from which  the  class  inherits  and  the
  2394.         access restrictions (public,  protected, virtual, ...) and second
  2395.         the subclasses which inherit from  the  given  class,  also  with
  2396.         access  restrictions.  This  option  is useful to find out things
  2397.         like the class dependencies or multiple inheritance.
  2398.  
  2399.  
  2400.         -charwarn      (CFT, CST, DFT, FFT, LFT)
  2401.         Warning if unknown/illegal characters are  found  in  the  source
  2402.         code during analysis.  By default, there is no now no longer such
  2403.         a warning.
  2404.  
  2405.  
  2406.         -cmdline       (CFT, CST, DFT, FFT, LFT)
  2407.         Print the command line options at the  beginning  of  the  output
  2408.         file  as  a remark for the generation rules for that output file.
  2409.         All options and files specified  on  the  command  line,  in  the
  2410.         environment variable,  the commandlist and the filelist files are
  2411.         listed.
  2412.  
  2413.  
  2414.         -c[s]          (CFT, CST, DFT, FFT, LFT)
  2415.         Display the number of calls to each function/data type, 's' sorts
  2416.         by the number of calls (DEFAULT ORDER:  lexicographical).  Useful
  2417.         to  find  out  which  functions/data  types are never called/used
  2418.         (maybe unnecessary and deletable) and which  ones  are  the  most
  2419.         frequently  called/used (together with profiler results a subject
  2420.         for  further  optimization  efforts).   For  FFT  see  also   the
  2421.         description for option -CALL.
  2422.  
  2423.  
  2424.         -defmacro      (LFT)
  2425.         Recognise the 'defmacro' keyword in SCHEME source code.
  2426.  
  2427.  
  2428.         -dn            (CFT, CST, DFT, FFT, LFT)
  2429.         Set the maximum function/structure/union nesting level for output
  2430.         generation  to  'n' (DEFAULT: maximum value n = 999).  This means
  2431.         that the request for displaying a deeper level will  be  rejected
  2432.         and the output calltree will be truncated at the given level.
  2433.  
  2434.  
  2435.  
  2436.  
  2437.  
  2438.  
  2439.  
  2440.                                      - 40 -
  2441.  
  2442.  
  2443.         -e[char]       (CFT, CST, DFT, FFT, LFT)
  2444.         Generate  formatted ASCII text files with function/data type list
  2445.         and file list.  All entries are separated by the optional  'char'
  2446.         character,  if 'char ' is not defined, the tabulator character is
  2447.         used as DEFAULT SEPARATOR.  If spaces are  wanted  as  separating
  2448.         characters,  you have to write -e" ".  Such prepared files can be
  2449.         used directly as input to other  programs  like  word  processors
  2450.         (e.g.  MS-WORD  for  WINDOWS)  or  spreadsheet  calculators (e.g.
  2451.         MS-EXCEL), for example for documentation purposes.  The following
  2452.         files are created:
  2453.  
  2454.         CFTITEMS.TXT:
  2455.         Contents: function name,  return type,  filename, line #, total #
  2456.         of function bytes,  # of function comment bytes,  #  of  function
  2457.         lines, # of control statements, # of brace levels
  2458.  
  2459.         CSTITEMS.TXT:
  2460.         Contents: data type name, filename line #
  2461.  
  2462.         CFTFILES.TXT and CSTFILES.TXT:
  2463.         Contents: filename,  # of lines, file size in bytes, # of comment
  2464.         bytes, # of functions/data types
  2465.  
  2466.  
  2467.         -f             (CFT, CST, DFT, FFT, LFT)
  2468.         Generate  an  output  list  in  short   form,   only   with   the
  2469.         function/data type names,  no further description of the internal
  2470.         function/data type elements.
  2471.  
  2472.  
  2473.         -filetree      (CFT, CST, FFT)
  2474.         This option displays the file hierarchy  tree  for  every  source
  2475.         file.  The  look  of  the  file  hierarchy tree is similar to the
  2476.         function hierarchy tree.  Unless option -M  displays  the  'flat'
  2477.         source vs. include file relationsship, this option shows the real
  2478.         nested  source  file include file hierarchy tree.  This option is
  2479.         useful to see how the files are related  and  nested.  Note  that
  2480.         this  option  will  only  work  correctly if options -P or -I are
  2481.         used,  but not on preprocessed files.  There may also be problems
  2482.         with  files  produced  by source code generators like LEX/FLEX or
  2483.         YACC/BISON.
  2484.  
  2485.  
  2486.         -g[name]       (CFT, CST, DFT, FFT, LFT)
  2487.         Read  a  previously  generated  database  (see  option  -G).  The
  2488.         additional  parameter  'name'  (path  and filename) is used as an
  2489.         unique base  name  for  the  set  of  database  files  (up  to  6
  2490.         significant  characters),  the  DEFAULT  NAME 'CXT' is used if no
  2491.         name is specified. If 'name' ends with a (back-)slash, it is used
  2492.         as a pathname.  Every source file will be tested for  changes  of
  2493.         file  creation  time  and file size and a warning message will be
  2494.         given to inform the user.  It is currently not possible to update
  2495.         the results of such files.
  2496.  
  2497.  
  2498.  
  2499.  
  2500.  
  2501.                                      - 41 -
  2502.  
  2503.  
  2504.         -h[elp]        (CFT, CST, DFT, FFT, LFT)
  2505.         See option -?.
  2506.  
  2507.  
  2508.         -iname         (CFT, DFT, FFT, LFT)
  2509.         Ignore function member 'name' in output calltree.  It will not be
  2510.         displayed and will be skipped instead  if  found  as  a  function
  2511.         member.  For DFT and FFT the item names are considered uppercase.
  2512.         This option can be useful if,  for example,  functions  are  used
  2513.         only  for  test  purposes  and are of no further interest for the
  2514.         user and should be ignored in the output  calltree.  It  is  also
  2515.         possible  to  specifiy  library  functions  so  that  the  output
  2516.         calltree contains only user defined functions.
  2517.  
  2518.  
  2519.         -l             (CFT, DFT, FFT, LFT)
  2520.         List a function only once in case of repeated  consecutive  calls
  2521.         (DEFAULT: display every occurrence). If a function is called more
  2522.         than  one  time  inside  a  function  without  any  other call in
  2523.         between,  there will be only one reference of that function  call
  2524.         in  the  output  calltree.  This option results in shorter output
  2525.         files.
  2526.  
  2527.  
  2528.         -mtype         (CST)
  2529.         Start the data type tree chart with data  type  'type'  (-mtype).
  2530.         If  -m+  is  specified,  the  output starts with the topmost data
  2531.         type,  this is the data type which is in the highest level of the
  2532.         hierarchy  tree  chart.  The default output is in lexicographical
  2533.         order  of  the  displayed  data  types.   Useful  if  a  selected
  2534.         structure/union  should  be  displayed  at  the  beginning of the
  2535.         output file.
  2536.  
  2537.  
  2538.         -m[name]       (CFT, FFT)
  2539.         -mname         (DFT, LFT)
  2540.         Start the function calltree dump with function 'main'  (CFT  -m),
  2541.         'PROGRAM' (FFT -m) or 'name' (-mname), name is case sensitive. If
  2542.         -m+  is  specified,  the output starts with the topmost function,
  2543.         this is the function  which  is  in  the  highest  level  of  the
  2544.         hierarchy  calltree.  If  this option is not set,  the default is
  2545.         lexicographical order of the displayed functions.
  2546.  
  2547.         Usually,  the complete function calltree should  start  with  the
  2548.         'main'  function  so  that every subfunction is a (sub-)member of
  2549.         'main'.  This option is useful for windows programs to start  the
  2550.         output with the initial 'WinMain' function (-mWinMain) instead of
  2551.         'main'.  It can also be used to start the output with the initial
  2552.         assembler start-up code being executed before the 'main'-function
  2553.         is called.
  2554.  
  2555.  
  2556.         -n[a]          (CFT, CST, DFT, FFT, LFT)
  2557.         Display the most critical function call path respectively display
  2558.         the data structure/union with  the  maximum  nesting  level.  The
  2559.         modificator  'a' is used to display every function/structure with
  2560.  
  2561.  
  2562.                                      - 42 -
  2563.  
  2564.  
  2565.         its users/callers (DEFAULT: display only deepest call path). This
  2566.         option  helps  to  determine  the  complexity  of  the   function
  2567.         call/data  structure  hierarchy and finds recursions over several
  2568.         call/nesting levels.  Note that for functions  the  maximum  call
  2569.         path  being  displayed  is  the  result of the static source code
  2570.         analysis.  During program execution the call  path  can  be  even
  2571.         deeper  if functions are called indirectly with function pointers
  2572.         or similar mechanisms.
  2573.  
  2574.  
  2575.         -noundef       (CFT, DFT, FFT, LFT)
  2576.         Ignore  undefined  items  (functions,   subroutines)  in   output
  2577.         calltree.  Display  only  those  which  are really defined in the
  2578.         analysed source code.
  2579.  
  2580.  
  2581.         -ofile         (CFT, CST, DFT, FFT, LFT)
  2582.         Write the generated analysis  results  to  file  'file'.  DEFAULT
  2583.         BEHAVIOUR:  The filenames are 'CFT.LST' for CFT and 'CST.LST' for
  2584.         CST.  Possible overwriting of an existing output  file  with  the
  2585.         same  name  other  than  the  default  one  will  be detected and
  2586.         prompted for user reconfirming.  The resulting output file is  an
  2587.         ASCII  text  file  with  no  formatting  characters  which can be
  2588.         printed with every printer,  viewed and/or edited with every text
  2589.         editor  and  taken  as input to word processors,  for example for
  2590.         documentation purposes.
  2591.  
  2592.  
  2593.         -p             (CFT, CST, DFT, FFT, LFT)
  2594.         Calculate the program code/file size ratio  for  every  file  and
  2595.         make  a  final summary.  This option gives a short overview about
  2596.         the 'real' file contents versus complexity. The computed value is
  2597.         in the range from 0.000 (only comment,  no code) to  1.000  (only
  2598.         code,  no comment). Used together with -P, the results may not be
  2599.         absolutely correct because of the macro expanding and removing of
  2600.         parts  of  the  source  code  by  '#if...'  control  blocks.   If
  2601.         preprocessing -P is enabled, comment byte count in included files
  2602.         will not be performed. If option -q is set, -p will not calculate
  2603.         values related with comments.
  2604.  
  2605.  
  2606.         -q             (CFT, CST)
  2607.         Remove comments from preprocessed files, default is don't remove.
  2608.         This option is only valid with option -P,  it also affects the -p
  2609.         option because counting comments is not possible and calculations
  2610.         on them cannot be done.
  2611.  
  2612.  
  2613.         -qn            (FFT)
  2614.         Set the number of continuation lines to 'n' (DEFAULT: 19  lines).
  2615.         The number must be in the range from 0 to 99.
  2616.  
  2617.  
  2618.  
  2619.  
  2620.  
  2621.  
  2622.  
  2623.                                      - 43 -
  2624.  
  2625.  
  2626.         -r             (CFT, CST, DFT, FFT, LFT)
  2627.         This  is  almost  the  same as option -x,  but an additional file
  2628.         reference  with  the  filename  and  the  line  number   of   the
  2629.         declaration will be given (includes -x).
  2630.  
  2631.         The  -r  or  the  -x option is STRICTLY RECOMMENDED and should be
  2632.         used as a default option, because without it, every function/data
  2633.         type will be completely  redisplayed,  including  the  underlying
  2634.         subtree  of  functions  or data types,  whenever it occurs in the
  2635.         output tree chart and so the  resulting  output  file  will  grow
  2636.         immense,  up to several megabytes,  if there is enough disk space
  2637.         to write the output file.
  2638.  
  2639.  
  2640.         -s             (CFT, CST, FFT, LFT)
  2641.         Used with -C,  this option gives additional information.  For CFT
  2642.         for  every  function:  the number of lines for the function body,
  2643.         the maximum brace levels,  the number of bytes for  the  function
  2644.         body  and  the  number of comment bytes inside the function body.
  2645.         The average  values  for  every  source  file  are  computed  and
  2646.         displayed.  For CST for every data type: number of type elements,
  2647.         number of subelements (nested structures/unions).
  2648.  
  2649.  
  2650.         -time          (CFT, CST, DFT, FFT, LFT)
  2651.         Print runtime information about the  times  consumed  for  source
  2652.         analysis,   preprocessing,  output  dump,  database  reading  and
  2653.         writing and for other miscellaneous jobs plus the total time. The
  2654.         results are given in the format MINUTE:SECOND.MILLISECOND.
  2655.  
  2656.  
  2657.         -touch         (CFT, CST, DFT, FFT, LFT)
  2658.         If the file information in a database concerning  the  file  date
  2659.         and  the  file  size  is  out-of-date,  it will be updated if the
  2660.         database is read (option -g) and option -touch is set.  Useful to
  2661.         avoid  the  warnings e.g.  with the BRIEF macros.  However,  this
  2662.         option should only be used if the contents of the related  source
  2663.         files has not changed. This option does not reprocess and analyse
  2664.         the related sources, there will be no update of the results!
  2665.  
  2666.  
  2667.         -u             (CFT, DFT, FFT, LFT)
  2668.         List  undefined  functions.  These functions are probably library
  2669.         functions,  defined in other files which have not been scanned or
  2670.         are unresolved externals found by the linker.
  2671.  
  2672.  
  2673.         -vpath         (CFT, CST, FFT)
  2674.         Set a specific path for the intermediate precompiler output file.
  2675.         'path'  can  be a pathname or a drive letter with pathname,  e.g.
  2676.         'c:\tmp' or 'g:\' (not 'g:' without '\', this is an error).  This
  2677.         option   is   useful   to  speed  up  execution  speed  when  the
  2678.         intermediate file can be stored on a RAM-disk so that file access
  2679.         to the precompiled file is much faster than on a hard disk.  Test
  2680.  
  2681.  
  2682.  
  2683.  
  2684.                                      - 44 -
  2685.  
  2686.  
  2687.         have  shown  that  the analysis time can be reduced for more than
  2688.         25%.  Environment variables like 'TMP' or 'TEMP' to set the  path
  2689.         for temporary files are not evaluated.
  2690.  
  2691.  
  2692.         -x             (CFT, CST, DFT, FFT, LFT)
  2693.         Cross reference in case of multiple use.  Every function and data
  2694.         type  will  be  given  a  unique  reference  number  which   will
  2695.         furthermore  be  used  as an identifying reference number for the
  2696.         function or data type if it is again displayed.  See also  option
  2697.         -r for further descriptions.
  2698.  
  2699.  
  2700.         -y             (CFT, CST, DFT, FFT, LFT)
  2701.         Display  cross  link  list of files which contain referencing and
  2702.         referenced functions/data types  of  functions/data  types  of  a
  2703.         specific  file.  This option shows the relations in the following
  2704.         form:
  2705.  
  2706.              1. referencing file
  2707.              ...
  2708.              n. referencing file
  2709.         file
  2710.              1. referenced file
  2711.              ...
  2712.              m. referenced file
  2713.  
  2714.         This  option  is  useful  if  you  want  to  find  out  the  file
  2715.         relationships.  This  information can be used to isolate specific
  2716.         files from a project,  e.g.  library files.  It is also useful if
  2717.         you  want  to  separate  a  function and want to know which other
  2718.         files are needed because they contain called functions. Note that
  2719.         there  may  be  problems  with  files  produced  by  source  code
  2720.         generators like LEX/FLEX or YACC/BISON.
  2721.  
  2722.  
  2723.         -z             (CFT, CST, DFT, FFT, LFT)
  2724.         Generate  a  function/data  type call cross reference table.  For
  2725.         every function/data type the location of  its  definition  (file,
  2726.         line)  and  a  complete  list of its calls/references,  sorted by
  2727.         files and line numbers is given in the following form:
  2728.  
  2729.         1. function/data type (reference #) [file #], line #
  2730.              [file #]: line #, ...
  2731.              ...
  2732.  
  2733.         2. ...
  2734.              ...
  2735.  
  2736.         The functions/data types are displayed in lexicographical  order.
  2737.         At the end of the section is the cross reference file list.  Note
  2738.         that this option can be extremely time consuming if the number of
  2739.         source files is very large!
  2740.  
  2741.  
  2742.  
  2743.  
  2744.  
  2745.                                      - 45 -
  2746.  
  2747.  
  2748.         -$             (FFT)
  2749.         Recognise $ as identifier character, not as delimiter. Useful for
  2750.         source code written for VAX (VMS)- or IBM (MVS)-Fortran.
  2751.  
  2752.  
  2753.         -//            (CFT, CST)
  2754.         Accept C++ comments '//...' in C source code.  This option can be
  2755.         used  to  ensure  compatibility  with  C compilers which can also
  2756.         recognise C++ comments within C source code (like  Microsoft  and
  2757.         Borland).
  2758.  
  2759.  
  2760.         -?             (CFT, CST, DFT, FFT, LFT)
  2761.         Shows  the  command  line syntax and gives a short,  but complete
  2762.         help information about the accepted commands and their syntax.
  2763.  
  2764.  
  2765.  
  2766.         COMMAND LINE FILES
  2767.  
  2768.         cmdfile        (CFT, CST, DFT, FFT, LFT)
  2769.         Specifies a file with (additional)  command  line  options.  This
  2770.         might  be useful if the command line would be too long because of
  2771.         the number of options and files declared or if  you  are  usually
  2772.         using  the  same  options  which  can then be stored in a command
  2773.         file.  The initial '$'-character is required to  mark  a  command
  2774.         file.
  2775.  
  2776.         filelist       (CFT, CST, DFT, FFT, LFT)
  2777.         A  file with a list of source file(s) to be processed,  wildcards
  2778.         are accepted.  The list file should have every file on  a  single
  2779.         line.  The  rules  for  files  containing assembler code and path
  2780.         translation are described above.  The  initial  '@'-character  is
  2781.         required  to mark a filelist file.  The '+' sign for subdirectory
  2782.         processing is also possible inside the filelist file.
  2783.  
  2784.         [+]file        (CFT, CST, DFT, FFT, LFT)
  2785.         The name of a source file to be processed. More than one file can
  2786.         be specified on the command line.  The default assumption for the
  2787.         given files is that they contain C source code.  Assembler source
  2788.         files are only recognised by the  file  extension  '.ASM'  (80x86
  2789.         MASM/TASM) and '.S' (Intel 80960, GNU).
  2790.  
  2791.         The  '+' sign indicates that,  starting from the given directory,
  2792.         all subdirectories should be searched recursively for  the  given
  2793.         filename  search  pattern.  This  addition  is  useful if a large
  2794.         software project is divided into several  modules  with  separate
  2795.         subdirectories  for  each module.  In that case only the starting
  2796.         (root-)directory with the requested filename search pattern  must
  2797.         be   specified   to   search   the   current  directory  and  all
  2798.         subdirectories.
  2799.  
  2800.         If the filename or the include file specification inside  a  file
  2801.         contains a relative path ('./',  '.\', '../' or '..\') it will be
  2802.         translated into  an  absolute  path  starting  from  the  current
  2803.  
  2804.  
  2805.  
  2806.                                      - 46 -
  2807.  
  2808.  
  2809.         working directory respectively in case of include files depending
  2810.         on  the  path of the parent file.  Command line wildcards '*' and
  2811.         '?' are possible and will be accepted.
  2812.  
  2813.  
  2814.         REMARKS ON USING OPTIONS
  2815.  
  2816.         NONE OF THE DESCRIBED OPTIONS IS PREDEFINED SO  IT'S  UP  TO  THE
  2817.         USER  HIMSELF TO CUSTOMIZE HIS PREFERRED PROCESSING BEHAVIOUR AND
  2818.         OUTPUT STYLE BY ADDING CONTROL OPTIONS NEEDED THEREFORE.
  2819.         This assumption seems to be the best way to give  the  users  the
  2820.         freedom  of  making  their  own decisions about the features they
  2821.         really need for doing their work.
  2822.  
  2823.         However,  some of the options should  be  regarded  and  used  as
  2824.         'DEFAULT'  options  to  generate a readable,  complete and useful
  2825.         output file without  unexpected  side  effects.  So  the  minimum
  2826.         default command lines look like
  2827.  
  2828.              CFT -m -r <files>
  2829.              CST -r <files>
  2830.  
  2831.         Both  command  sets  generate  a  complete listing containing all
  2832.         defined items with  filename  and  line  reference  and  a  cross
  2833.         reference id for repeated use (options -r). The option -m for CFT
  2834.         forces  the  output to start with the 'main' function (if found).
  2835.         The precompile option -P is not  strictly  necessary  though  for
  2836.         exact  results it should also be set together with the -T option.
  2837.         The standard default command line might be
  2838.  
  2839.              CFT -m -ruspMP -T<type> -cs -Cs -n -Zs -G <file[s]>
  2840.              CST -rpMP -T<type> -cs -Cs -n -Zs -G <file[s]>
  2841.  
  2842.         If you start using CFT and CST for your own business,  take these
  2843.         options as a basic set and try other options to get a feeling for
  2844.         what they are useful and how they affect the output.
  2845.  
  2846.         The  large  number  of options may be confusing for beginners but
  2847.         this is the only way to give users the flexibility of customising
  2848.         their own output.  Therefore,  take some time to learn about  CFT
  2849.         and  CST and their features,  read this manual carefully and make
  2850.         your own experiences with this software.
  2851.  
  2852.         It is possible to declare more than one source file, command file
  2853.         and list file on the command line.  In that  case  they  will  be
  2854.         processed  in  the  order  they appear.  Files and options can be
  2855.         placed  in  mixed  order  on  the  command  line,   there  is  no
  2856.         recommended order for them because all options (also those inside
  2857.         command  files!)  will  be  processed before any source files are
  2858.         scanned.
  2859.  
  2860.         The maximum command line length for DOS  is  127  characters,  so
  2861.         this  is  a  system dependent 'natural' limit for the options and
  2862.         filenames being declared.  If you have  more  items  to  declare,
  2863.         place them into command list files and file list files,  which do
  2864.         not have such limitations.
  2865.  
  2866.  
  2867.                                      - 47 -
  2868.  
  2869.  
  2870.  
  2871.         Options can also be defined by the environment variables CFT  and
  2872.         CST like
  2873.  
  2874.              SET CFT=...
  2875.              SET CST=...
  2876.  
  2877.         To separate single options in the environment string,  spaces are
  2878.         required.  See also the description for the -D option for remarks
  2879.         on environment variable definitions.
  2880.  
  2881.         The rules for the interpretation of options is
  2882.  
  2883.         1.   if  defined,  all  options  in the environment variables CFT
  2884.              (for CFT) or CST (for CST) will be taken,
  2885.         2.   the command line  options  and  the  option  files  will  be
  2886.              interpreted in the order they appear.
  2887.  
  2888.         If  an  option is declared different more than once then previous
  2889.         declarations will be overwritten by the newer one.
  2890.  
  2891.         If  options  are  represented  by  a  single  character  with  no
  2892.         additional  optional  values possible like -r or -a,  they can be
  2893.         grouped together with a single leading '-' in front like '-rasM',
  2894.         which is the same as '-r -a -s -M'. The last option however,  can
  2895.         have   additions,   for  example  '-rasMmWinMain'  which  can  be
  2896.         evaluated to '-r -a -s -M -mWinMain'.  If an option can  have  an
  2897.         additional  parameter,  the parameter must be specified without a
  2898.         space between the option character. Leaving this space means that
  2899.         no additional parameter is given for this option.
  2900.  
  2901.         Filenames  being  composed  of  drive  letter,   directory  name,
  2902.         filename and file extension,  in the following referred simply as
  2903.         'pathname',  are treated by some special procedures  to  force  a
  2904.         unique style of their internal representation:
  2905.  
  2906.         -    path  names  are  always  considered not case sensitive,  so
  2907.              there is no difference in upper case,  lower case and  mixed
  2908.              case  path  names  (the reason is that DOS does not make any
  2909.              difference),
  2910.         -    path names containing './', '.\', '../' and '..\' (so called
  2911.              'relative paths') are expanded and transformed into absolute
  2912.              paths,
  2913.         -    the recommended directory delimiter is '/' (UNIX-style),  if
  2914.              a  '\' (DOS-style) is recognised in a path name,  it will be
  2915.              replaced by '/',
  2916.         -    path names are always  expanded  and  transformed  into  the
  2917.              default style
  2918.  
  2919.                   <DRIVE LETTER>:<DIRECTORY PATH>/<FILENAME>
  2920.  
  2921.              to  get a unique representation for every filename that must
  2922.              be handled during processing,
  2923.  
  2924.  
  2925.  
  2926.  
  2927.  
  2928.                                      - 48 -
  2929.  
  2930.  
  2931.         -    filenames have a DOS like maximum length of  12  characters:
  2932.              '<8 characters name>.<3 characters extension>', this is also
  2933.              true  for  the  Windows  NT  and  OS/2  versions  of the SXT
  2934.              programs.
  2935.  
  2936.         These  actions  are  done  with  every  path  name  during   file
  2937.         processing.   Filenames  given  on  the  command  line  are  also
  2938.         transformed.
  2939.  
  2940.         If you want  to  perform  database  generation  (option  -G)  for
  2941.         different  projects,  you  are  responsible  to separate them and
  2942.         avoid overwriting of existing databases.  This can be done either
  2943.         by  giving  the  databases  different  names so that the database
  2944.         files can be placed all in the same directory,  or every database
  2945.         must be written into its own directory. If you want to access the
  2946.         databases  be  sure  to  use  the correct name and/or path,  also
  2947.         within the BRIEF or MicroEMACS editors.
  2948.  
  2949.  
  2950.  
  2951.  
  2952.  
  2953.  
  2954.  
  2955.  
  2956.  
  2957.  
  2958.  
  2959.  
  2960.  
  2961.  
  2962.  
  2963.  
  2964.  
  2965.  
  2966.  
  2967.  
  2968.  
  2969.  
  2970.  
  2971.  
  2972.  
  2973.  
  2974.  
  2975.  
  2976.  
  2977.  
  2978.  
  2979.  
  2980.  
  2981.  
  2982.  
  2983.  
  2984.  
  2985.  
  2986.  
  2987.  
  2988.  
  2989.                                      - 49 -
  2990.  
  2991.  
  2992.         COMMAND LINE EXAMPLES
  2993.  
  2994.         1.   CFT -m -rau *.c
  2995.         This program invocation of  CFT  processes  all  files  with  the
  2996.         extension  ".c"  in the current directory and generates an output
  2997.         file starting with the "main"-function (option -m) for the output
  2998.         tree.  Every function will be displayed with file and line number
  2999.         reference and a cross reference number (option -r). All functions
  3000.         will be shown in lexicographical order (-a),  also undefined ones
  3001.         (-u).
  3002.  
  3003.         2.   CFT -mWinMain -rausMP -TMSC70,L -Id: -cs -Cs -na -ve:\  -C++
  3004.              *.c ..\*.c *.cpp
  3005.         This  invocation  is similar to the one described above with some
  3006.         extensions.  The source files from the current (*.c,  *.cpp)  and
  3007.         from  the  parent  (..\*.c) directory,  they will be preprocessed
  3008.         (-P) with MS-C 7.0 defines for large  memory  model  (-TMSC70,L),
  3009.         the include file path will be taken from the environment variable
  3010.         "INCLUDE"  (default for -P) and the path "d:" (-Id:) will also be
  3011.         searched for.  The precompiler output  is  stored  in  path  "e:"
  3012.         (-ve:\).  C++  extensions and keywords will be recognised if they
  3013.         occur (-C++).  The output will start with the  "WinMain"-function
  3014.         (-mWinMain).  There  will  be a sorted call statistic (-cs) and a
  3015.         function summary for every scanned  file  (-Cs)  with  additional
  3016.         information  for every function (-s).  The critical function call
  3017.         path for all functions will be calculated and displayed (-na) and
  3018.         the included files of every source file will be shown (-M).
  3019.  
  3020.         3.   CST -S"struct _test" -r *.h -W2 -C++
  3021.         Start CST to  scan  all  files  in  the  current  directory  with
  3022.         extension  ".h"  for  data  types.  They  will  be displayed with
  3023.         filename and line number reference  and  cross  reference  number
  3024.         (-r).  The output should be done for the data type 'struct _test'
  3025.         (-S"struct _test"). The warning level is set to "2" (-W2).
  3026.  
  3027.         4.   CFT y.c -R -Dmain=main_entry z.c -P x.c
  3028.         Start CFT to produce a reverse calling tree (-R) of the functions
  3029.         found in  the  files  "x.c",  "y.c"  and  "z.c"  in  the  current
  3030.         directory.  The files will be preprocessed (-P) before file scan,
  3031.         the  name  "main"  will  be  replaced  by   "main_entry"   during
  3032.         preprocessing (-Dmain=main_entry).
  3033.  
  3034.         5.   CST $cst1.cmd $cst2.cmd -ve:\tmp @cstfiles +*.h -olist.v1a
  3035.         This  invocation  of  CST  receives  its options from the command
  3036.         files "cst1.cmd"  and  "cst2.cmd"  and  stores  the  preprocessor
  3037.         output in path "e:\tmp" (-ve:\tmp). The files being processed are
  3038.         defined  in  the  source  list file "cstfiles" and on the command
  3039.         line by  "+*.h".  The  "+*.h"  file  specification  searches  the
  3040.         current  directory  and  all  subdirectories  for  files with the
  3041.         extension  ".h".   The  output  file  will  be  named  "list.v1a"
  3042.         (-olist.v1a).
  3043.  
  3044.  
  3045.  
  3046.  
  3047.  
  3048.  
  3049.  
  3050.                                      - 50 -
  3051.  
  3052.  
  3053.         6.   CFT -ra -PGNUINC -TGNU -M c:\gnu\src\*.c c:\gnu\src\*.s -d10
  3054.         CFT scans all files with extension ".c" and ".s" in the directory
  3055.         "c:\gnu\src". They will be preprocessed with an include file path
  3056.         defined  in environment variable "GNUINC" (-PGNUINC) for compiler
  3057.         type "GNU" (-TGNU).  The output contains all functions (-a)  with
  3058.         complete  reference  information  (-r) and a list of all included
  3059.         files for every  source  file  (-M).  The  output  tree  will  be
  3060.         truncated if the nesting level is higher than 10 (-d10).
  3061.  
  3062.         7.   CST *.c
  3063.         CST  processes  all  files  with  extension  ".c"  in the current
  3064.         working directory.  There are no options specified,  so only  the
  3065.         options set by the environment variable 'CST',  if present,  will
  3066.         be used to customise the program execution.  As  an  example  the
  3067.         command  line  options  used  in  example  6.  can  be defined as
  3068.         environment variable CST by 'SET CST=-raMKPGNUINC -TGNU -d10'.
  3069.  
  3070.         8.   CFT -ra -PI960INC -TI960,KB *.c *.s
  3071.         CFT scans all files with extension ".c" and ".s" in  the  current
  3072.         directory.  They  will  be preprocessed with an include file path
  3073.         defined  in  environment  variable  "I960INC"   (-PI960INC)   for
  3074.         compiler type "I960",  'KB' architecture (-TI960,KB).  The output
  3075.         contains all functions (-a) with complete  reference  information
  3076.         (-r).
  3077.  
  3078.         9.   CFT -rR -M -gproj40 -Gproj41
  3079.         CFT reads the database named 'proj40' (-g) and produces as output
  3080.         the  reverse  function  call  tree  (-R)  with complete reference
  3081.         information (-r), the (include) file interdependencies (-M) and a
  3082.         new database named 'proj41'.
  3083.  
  3084.         10.  CST -g -Gnew -N
  3085.         CST reads the  default  database  (-g)  and  produces  as  output
  3086.         another  database  named  'new' (-Gnew).  No other output file is
  3087.         generated (-N).
  3088.  
  3089.         11.  CST -N -OTEST -O+ test.h
  3090.         CST reads the file "test.h", generates no output file (-N), but a
  3091.         byte offset calculation file for data type  'TEST'  (-OTEST)  and
  3092.         its enclosed type members (-O+).
  3093.  
  3094.  
  3095.  
  3096.  
  3097.  
  3098.  
  3099.  
  3100.  
  3101.  
  3102.  
  3103.  
  3104.  
  3105.  
  3106.  
  3107.  
  3108.  
  3109.  
  3110.  
  3111.                                      - 51 -
  3112.  
  3113.  
  3114.         8    OUTPUT DESCRIPTION AND INTERPRETATION
  3115.  
  3116.         This section gives an overview about the files being generated by
  3117.         CFT  and  CST  and  the interpretation of the results.  Different
  3118.         files are produced as output depending on the options  being  set
  3119.         by  the  user.  Usually,  if  -N is not set,  all information are
  3120.         written to the default output file CFT.LST or CST.LST or  to  the
  3121.         file specified by the -o option.  The internal structure of these
  3122.         files  and  their  meanings  are  described  below.  If  database
  3123.         generation is enabled with option -G, several files are produced.
  3124.         They  all  have a common database name to identify the files that
  3125.         are related with a project.  The file extension '.DBF' marks  the
  3126.         dBASE  compatible  database  files,  the  file with the extension
  3127.         '.CMD' contains the command line options and the  file  with  the
  3128.         extension  '.SRC'  contains all source files that were processed.
  3129.         For further information refer to the corresponding section in the
  3130.         syntax description.
  3131.  
  3132.  
  3133.         CFT OUTPUT
  3134.  
  3135.         The output file is divided into several  sections.  Some  of  the
  3136.         sections listed are generated by default (-), others are optional
  3137.         (o)  and  only  displayed  if  they are enabled by a command line
  3138.         option.  Also,  the default sections can be customised to produce
  3139.         the  desired  output.  The sections generated for CFT are (in the
  3140.         order they appear):
  3141.  
  3142.         -    file header
  3143.         -    function calltree/called-by hierarchy listing (-r,  -R,  -x,
  3144.              -a, -m, -f, -dn, -V, -l)
  3145.         -    function summary
  3146.         -    multiple  defined  functions  and  their  location  (only if
  3147.              detected)
  3148.         -    overloaded functions and their location (only if detected)
  3149.         o    undefined functions (-u)
  3150.         o    function call statistics (-c[s])
  3151.         o    function caller/member relations (-Z[s])
  3152.         o    function call cross reference table (-z)
  3153.         o    critical function call path (-n[a])
  3154.         o    source file - include file dependency (-M)
  3155.         o    function tables for source files (-C[s], -s, -q)
  3156.         -    file information summary (-p, -q)
  3157.  
  3158.         Each function is displayed like:
  3159.  
  3160.              int test()  (1) <DMPCA> <TEST.C, 100>
  3161.  
  3162.         with the following meanings
  3163.  
  3164.              - int          : function return type
  3165.              - test()       : function name
  3166.              - (1)          : function reference number
  3167.  
  3168.  
  3169.  
  3170.  
  3171.  
  3172.                                      - 52 -
  3173.  
  3174.  
  3175.              - <DMPCA>      : found as (one or more of)
  3176.                                  D = definition,
  3177.                                  M = macro,
  3178.                                  P = prototype,
  3179.                                  C = function call,
  3180.                                  A = assembler function
  3181.              - <TEST.C, 100>: filename, line number
  3182.  
  3183.         The line number is the line where the function  definition  block
  3184.         starts  with  its initial '{' and not the line where the function
  3185.         name resides.  I think that this is the best solution because  it
  3186.         is  the point where we go really inside the function block.  This
  3187.         convention is also used by source level debuggers which point  on
  3188.         the line with the opening brace on function entry.
  3189.  
  3190.  
  3191.         CST OUTPUT
  3192.  
  3193.         The  output  file  is divided into several sections.  Some of the
  3194.         sections listed are generated by default (-), others are optional
  3195.         (o) and only displayed if they are  enabled  by  a  command  line
  3196.         option.  Also,  the default sections can be customised to produce
  3197.         the desired output.  The sections generated for CST are  (in  the
  3198.         order they appear):
  3199.  
  3200.         -    file header
  3201.         -    data structure calltree/called-by hierarchy listing (-r, -R,
  3202.              -x, -a, -m, -f, -dn)
  3203.         -    data type summary
  3204.         -    multiple  defined  data  types  and  their location (only if
  3205.              detected)
  3206.         o    data type call statistics (-c[s])
  3207.         o    data type caller/member relations (-Z[s])
  3208.         o    data type call cross reference table (-z)
  3209.         o    maximum data type nesting (-n[a])
  3210.         o    source file - include file dependency (-M)
  3211.         o    data type tables for source files (-C[s], -s, -q)
  3212.         -    file information summary (-p, -q)
  3213.  
  3214.         Each data type is displayed like:
  3215.  
  3216.              struct _test  (1) <BSUCE> <TEST.C, 90> <TEST.C, 60>
  3217.  
  3218.         with the following meanings
  3219.  
  3220.              - struct _test : type specifier
  3221.              - (1)          : reference number
  3222.              - <BSUCE>      : data type (one/none of):
  3223.                                  B = basic type (void, char, int, ...),
  3224.                                  S = struct,
  3225.                                  U = union,
  3226.                                  C = class,
  3227.                                  E = enum
  3228.  
  3229.  
  3230.  
  3231.  
  3232.  
  3233.                                      - 53 -
  3234.  
  3235.  
  3236.              - <TEST.C, 90> : filename, line number of type definition
  3237.                               (only printed if necessary)
  3238.              - <TEST.C, 60> : filename, line number of basic type
  3239.                               definition
  3240.  
  3241.         The two locations for the data type can occur if the data type is
  3242.         first defined and later assigned via 'typedef'  or  by  '#define'
  3243.         (if -P is not set) to another data type name:
  3244.  
  3245.         test.c:   ...
  3246.         line 60:  struct xyz {...};
  3247.                   ...
  3248.         line 90:  typedef struct xyz struct _test;
  3249.                   ...
  3250.  
  3251.         Their  definition  is on different lines but both data type names
  3252.         refer to the same data structure.
  3253.  
  3254.         Like the convention used for functions,  the line number  is  the
  3255.         line  where  the  structure,  union,  enumeration  or  class type
  3256.         definition block starts with its initial '{'  and  not  the  line
  3257.         where the type name resides.
  3258.  
  3259.         For  an  example  session and more detailed information about the
  3260.         generated output of CFT and CST see the file EXAMPLE.DOC.
  3261.  
  3262.  
  3263.         OUTPUT INTERPRETATION
  3264.  
  3265.         Besides the hierarchical structure chart of the function and data
  3266.         type relationships,  the resulting output contains several useful
  3267.         information about the program which can be used for optimization,
  3268.         reuse  or  maintenance purposes.  Identifying the most frequently
  3269.         called functions is a good way to  find  candidates  for  further
  3270.         optimization. Low-level functions with many callers but no called
  3271.         subfunctions  are ideal for reuse.  Functions with no callers may
  3272.         be obsolete if the function  is  also  not  called  via  function
  3273.         pointers,  and  can  be  discarded therefore.  The chance to find
  3274.         errors in complex functions with many lines of source code,  many
  3275.         called  functions  and a lot of control statements is much bigger
  3276.         than in simple functions.
  3277.  
  3278.  
  3279.  
  3280.  
  3281.  
  3282.  
  3283.  
  3284.  
  3285.  
  3286.  
  3287.  
  3288.  
  3289.  
  3290.  
  3291.  
  3292.  
  3293.  
  3294.                                      - 54 -
  3295.  
  3296.  
  3297.         9    INTEGRATION INTO PROGRAM DEVELOPMENT ENVIRONMENTS
  3298.  
  3299.         Invoking CFT and CST directly from inside editors  or  integrated
  3300.         programming  environments (IDE) and displaying the results can be
  3301.         a very useful feature during program development.  With  advanced
  3302.         IDE's  like  that of Borland C++ or Microsoft PWB this is an easy
  3303.         task.
  3304.  
  3305.         The Borland IDE has in its system menu a section  with  'transfer
  3306.         items.  It  contains programs that can be invoked from inside the
  3307.         IDE like TASM or GREP. To add CFT and CST as new entries you have
  3308.         to go to the OPTIONS menu and open 'TRANSFERS...'.  Choose a free
  3309.         entry  in  the  table and select EDIT.  A window will open with 3
  3310.         edit lines.  In first line called 'Program Title' you must  write
  3311.         'C~FT'  resp.  'C~ST' as the name being displayed in the transfer
  3312.         section. The '~' prepends the hot-keys 'F' and 'S'. In the second
  3313.         line  called  'Program  Path'  you  must  write  'CFTIDE'   resp.
  3314.         'CSTIDE',  maybe with the complete path,  if necessary.  'CFTIDE'
  3315.         and 'CSTIDE' are batch files which perform the invocation of  CFT
  3316.         resp.  CST together with the necessary options. These batch files
  3317.         are part of the CXT package,  you can change the options  defined
  3318.         there  if you need other ones.  In the third line called 'Command
  3319.         Line' you must write the macro  commands  '$EDNAME  $NOSWAP  $CAP
  3320.         EDIT'.  These  macros  transfer  the filename in the current edit
  3321.         window ($EDNAME) to the  batch  file,  suppress  window  swapping
  3322.         ($NOSWAP)  and  capture  the  processing  results  in an own edit
  3323.         window ($CAP EDIT). The last step is to save these entries,  then
  3324.         the  integration  is  completed and CFT and CST can be used as if
  3325.         they were built-in functions. The processing results are shown in
  3326.         an edit window which can be scrolled, resized or moved. By adding
  3327.         CFT and CST to the IDE it is much easier for  the  programmer  to
  3328.         use these tools.
  3329.  
  3330.  
  3331.  
  3332.  
  3333.  
  3334.  
  3335.  
  3336.  
  3337.  
  3338.  
  3339.  
  3340.  
  3341.  
  3342.  
  3343.  
  3344.  
  3345.  
  3346.  
  3347.  
  3348.  
  3349.  
  3350.  
  3351.  
  3352.  
  3353.  
  3354.  
  3355.                                      - 55 -
  3356.  
  3357.  
  3358.         10   TOOLS FOR DATABASE PROCESSING
  3359.  
  3360.         To  access  information  stored  in  a  database,  the  following
  3361.         utilities are available for the SXT programs:
  3362.  
  3363.              CFTN      C Function Tree Navigator
  3364.              CSTN      C Structure Tree Navigator
  3365.              DFTN      DBASE Function Tree Navigator
  3366.              FFTN      FORTRAN Function Tree Navigator
  3367.              LFTN      LISP Function Tree Navigator
  3368.  
  3369.         They can be used to recall the filename  and  line  number  of  a
  3370.         specific  item (function or data type) from the database.  If the
  3371.         requested item is found in the database,  it  will  be  displayed
  3372.         with  its  location  where it is defined or where it is found for
  3373.         the  first  time  if  there  was  no  definition   found   during
  3374.         processing.
  3375.  
  3376.         As an additional feature editors like BRIEF 3.0, QEDIT 2.1/3.0 or
  3377.         MicroEMACS  3.11  can be invoked directly with the information to
  3378.         open the target file and to move the cursor to the line where the
  3379.         searched item is located.  For BRIEF  there  are  several  macros
  3380.         available  to  perform  searching  inside the editor.  A new edit
  3381.         window with the file at the location of the requested  item  will
  3382.         be  opened  if  the  search was successful.  Also both MicroEMACS
  3383.         editor versions for DOS and WINDOWS are supported.  Some of these
  3384.         actions are also possible for QEDIT,  with slight limitations due
  3385.         to the macro programming capabilities.
  3386.  
  3387.         Other user programmable editors which should be able to work with
  3388.         CFTN  and  CSTN  are  e.g.   CRISP  and  Codewright  (both  BRIEF
  3389.         compatible), EPSILON, ME, KEDIT, Multi-Edit, JED, GNU-EMACS ports
  3390.         like  DEMACS  or  OEMACS,  the  Microsoft  editor M or integrated
  3391.         development environments like Borland IDE or Microsoft PWB  (this
  3392.         list may not be complete). You can try to integrate CFTN and CSTN
  3393.         into these systems by using the BRIEF,  QEDIT or MicroEMACS macro
  3394.         files as examples for your own integration development.
  3395.  
  3396.         The version numbers for the  editors  mentioned  in  this  manual
  3397.         indicate those versions for which the described capabilities have
  3398.         been tested.
  3399.  
  3400.         PRECOMPILED SOURCE FILES
  3401.  
  3402.         Sometimes,  if  the  precompile option -P was used to process the
  3403.         C/C++ source files related with  the  database,  the  results  of
  3404.         searches  seem  to be wrong.  This can happen if an identifier in
  3405.         the source code is in fact  defined  as  a  macro  and  has  been
  3406.         exchanged  during  preprocessing  so  that  the  resulting source
  3407.         processed by the analyser is different from the  original  source
  3408.         and  the cursor will point to an obviously  wrong location or the
  3409.         search will fail.  An identifier which is in fact a macro name is
  3410.         unknown  and  not  accessible  after  precompiling.  It  is  also
  3411.         possible that a function being used in the original source  could
  3412.         not be found in the database.  The reason is that the function is
  3413.         in  fact  a  'function  like'  macro  and  was  replaced   during
  3414.  
  3415.  
  3416.                                      - 56 -
  3417.  
  3418.  
  3419.         preprocessing.  If  different  named macros are defined equal,  a
  3420.         search for an  item  may  point  to  another  location  than  the
  3421.         requested.  If  the -P option is not set,  the same item can have
  3422.         several 'alias'- names due to macro defining.  If the source code
  3423.         contains  explicit  #line numbers,  searching for a specific line
  3424.         may also fail.  Keep these  exceptions  in  mind  for  a  correct
  3425.         interpretation the results when using the database.
  3426.  
  3427.         IMPORTANT NOTICE
  3428.  
  3429.         Recalling information from the database may not be valid if files
  3430.         being  processed  were  edited  and  changed  after  the database
  3431.         generation has been performed. Errors can result like pointing to
  3432.         wrong files and/or lines if source lines  have  been  deleted  or
  3433.         inserted,  failed  searches  if  names  have  changed  or  failed
  3434.         accesses to files which may have been renamed,  moved or deleted.
  3435.         To avoid these errors,  a consistency check for the file creation
  3436.         date/time and file size will be performed by the recall programs.
  3437.         If inconsistencies are recognised, the user will be informed that
  3438.         the  database  is  not  up-to-date  and  should  be  updated   by
  3439.         processing the source files again.
  3440.  
  3441.  
  3442.         IMPORTANT  NOTICE TO DEVELOPERS USING THE DATABASE FROM THEIR OWN
  3443.         PROGRAMS
  3444.  
  3445.         There is absolutely  no  guarantee  that  the  internal  database
  3446.         structure will remain unchanged.  The internal database structure
  3447.         may change without notice.
  3448.  
  3449.  
  3450.         COMMAND LINE SYNTAX DESCRIPTION
  3451.  
  3452.         SYNTAX:   CFTN [options] pattern
  3453.                   CSTN [options] pattern
  3454.                   DFTN [options] pattern
  3455.                   FFTN [options] pattern
  3456.                   LFTN [options] pattern
  3457.  
  3458.         OPTIONS
  3459.  
  3460.         -Eeditor
  3461.         Specifies the editor command line for option -e,  overwrites  the
  3462.         default  and  the  environment  values.  See  the  section  about
  3463.         environment variables for further information about the  required
  3464.         format.
  3465.  
  3466.         -F
  3467.         Print  all  filenames  which are related with the database.  This
  3468.         option is useful to get a complete overview about  all  files  of
  3469.         the project.
  3470.  
  3471.         -a
  3472.         Print all function/data type names.  Useful to generate a list of
  3473.         items, for example as input to other programs.
  3474.  
  3475.  
  3476.  
  3477.                                      - 57 -
  3478.  
  3479.  
  3480.         -B
  3481.         Same as -a,  but prints additionally the internal database record
  3482.         number. Used by BRIEF macros.
  3483.  
  3484.         -bform
  3485.         Run search in batch-mode,  this means that, if the requested item
  3486.         was found,  the location will be displayed on a  single  line  as
  3487.         "file name line number" (DEFAULT STYLE),  otherwise there will be
  3488.         no output that the search failed. The output style can be changed
  3489.         by specifying 'form' to overwrite the  default  style.  Like  for
  3490.         option  -E you can specify the exact locations where the filename
  3491.         and line number should be inserted by defining  a  format  string
  3492.         with   %s   and  %d  (See  also  the  section  about  environment
  3493.         variables).  For example,  the format to generate a command  line
  3494.         for invoking BRIEF, QEDIT or MicroEMACS would look like
  3495.  
  3496.              cstn -b"b -m\"goto_line %d\" %s" ...         (BRIEF)
  3497.              cstn -b"q %s -n%d" ...                       (QEDIT)
  3498.              cstn -b"me -G%d %s"                          (MicroEMACS)
  3499.  
  3500.         This option gives you a great flexibility in generating an output
  3501.         for  your own purposes,  for example to write a batch file or for
  3502.         further use in other programs.
  3503.  
  3504.         -e
  3505.         If the requested item is found,  an editor  will  be  invoked  to
  3506.         display  the file containing the requested item.  There are three
  3507.         different ways to specify the editor command line  (evaluated  in
  3508.         that order):
  3509.  
  3510.         1)   use option -E,
  3511.         2)   define  the  environment  variables  CFTNEDIT,  CSTNEDIT  or
  3512.              CXTNEDIT,
  3513.         3)   if nothing is specified,  BRIEF as the  default  editor  (if
  3514.              present)  will  be invoked with the filename and line number
  3515.              of the item to move the cursor to its location.  Ensure that
  3516.              the  PATH  environment variable is set correctly,  including
  3517.              the path for the BRIEF directory.
  3518.  
  3519.         -fname
  3520.         Use 'name' as base name (path and filename) for  database  files.
  3521.         It  is  also  possible  to  use  environment variables (CFTNBASE,
  3522.         CSTNBASE, CXTNBASE) for the definition of the database names.  If
  3523.         -f and environment variables are not set,  a DEFAULT NAME will be
  3524.         used (see also option -G from CFT and  CST  syntax  description).
  3525.         This  allows  the  use  of  different  databases,   for  example,
  3526.         generated for different projects.  See  also  the  section  about
  3527.         environment variables for further information.
  3528.  
  3529.         -r#
  3530.         This option prints the location for a selected item with matching
  3531.         pattern  and  record number #.  This option requires -b.  Used by
  3532.         BRIEF macros.
  3533.  
  3534.  
  3535.  
  3536.  
  3537.  
  3538.                                      - 58 -
  3539.  
  3540.  
  3541.         -Ritem
  3542.         Print a cross reference list of every occurrence of  'item'  with
  3543.         complete filename and line number.
  3544.  
  3545.         -Dfile
  3546.         Print a list with the contents of 'file'.
  3547.  
  3548.         -o[name]
  3549.         Print output to file 'name'.  If 'name' is not specified, DEFAULT
  3550.         NAMES are used: CFTN.OUT resp. CSTN.OUT.
  3551.  
  3552.         pattern
  3553.         The item to search for in the database.  This  can  either  be  a
  3554.         function name (CFTN) or a data type name (CSTN).  There are three
  3555.         different ways of searching depending how 'pattern' is given:
  3556.  
  3557.         pattern        exact search,
  3558.         pattern*       the beginning of the item must match with pattern
  3559.         *pattern       a substring must match with pattern
  3560.  
  3561.         If the item  to  search  for  consists  of  more  than  one  word
  3562.         (contains  spaces),  the  search  pattern  must  be 'quoted' like
  3563.         "struct _iobuf" to ensure that these  words  are  interpreted  as
  3564.         single pattern.
  3565.  
  3566.  
  3567.         RETURN VALUES
  3568.  
  3569.         The  following  values are returned to DOS or the calling program
  3570.         to report the result of the database search:
  3571.  
  3572.         -    100  searched item not found,
  3573.         -    101  searched item found,
  3574.         -    102  searched item found,  but the source file may have been
  3575.                   changed  (creation date and/or file size are not equal)
  3576.                   since the creation of the  database  (database  is  not
  3577.                   up-to-date).
  3578.  
  3579.         The  returned  value  can be used to decide what action should be
  3580.         done for different results,  for example,  if the database is not
  3581.         up-to-date.
  3582.  
  3583.  
  3584.         ENVIRONMENT VARIABLES
  3585.  
  3586.         CFTNEDIT, CSTNEDIT, CXTNEDIT:
  3587.         The  editor  to  invoke  can be defined either by option -e or by
  3588.         defining the environment variables CFTNEDIT (for CFTN),  CSTNEDIT
  3589.         (for  CSTN) or the commonly used variable CXTNEDIT (for both CFTN
  3590.         and CSTN) with the format string of the editor  of  your  choice.
  3591.         The  format  string  can  be  used to specify the place where the
  3592.         filename  and  the  line  number  should  be  inserted  to   give
  3593.         additional information to the editor. Use %s for the filename and
  3594.         %d  for  the  line  number.  For  example,  the invocation of the
  3595.         default editor BRIEF could be defined like
  3596.  
  3597.  
  3598.  
  3599.                                      - 59 -
  3600.  
  3601.  
  3602.              SET CFTNEDIT=b -m"goto_line %d" %s
  3603.              SET CSTNEDIT=b -m"goto_line %d" %s
  3604.              SET CXTNEDIT=b -m"goto_line %d" %s
  3605.  
  3606.         where 'b' is the BRIEF editor,  '-m' specifies  the  macro  being
  3607.         invoked  when BRIEF starts,  the macro name 'goto_line' with '%d'
  3608.         as the place to insert the line number and '%s' as the place  for
  3609.         the  filename.  Note  that  this  example  cannot  be used on the
  3610.         command line with -E option because of the quotes. It is possible
  3611.         to change the order of %d and %s if another editor is used.
  3612.  
  3613.         Here are additional  configuration  examples  for  other  popular
  3614.         editors (examples are given for CFTN, similar for CSTN):
  3615.  
  3616.         EDIT (MS-DOS 5.0):  SET CFTNEDIT=edit %s  or  -E"edit %s"   or
  3617.                             SET CFTNEDIT=edit     or  -Eedit
  3618.  
  3619.         VDE 1.62:           SET CFTNEDIT=vde %s   or  -E"vde %s"    or
  3620.                             SET CFTNEDIT=vde      or  -Evde
  3621.  
  3622.         QEDIT 2.1/3.0:      SET CFTNEDIT=q %s -n%d   or   -E"q %s -n%d"
  3623.  
  3624.         MicroEMACS 3.11:    SET CFTNEDIT=me -G%d %s  or   -E"me -G%d %s"
  3625.  
  3626.         The described notation allows the user to customise CFTN and CSTN
  3627.         with  his  preferred  editor  and  to  perform additional actions
  3628.         during invocation. If your editor supports macro programming like
  3629.         BRIEF you are free to write your own macros to do similar  things
  3630.         like  the CXT.CM macro given for BRIEF 3.0 does.  I think this is
  3631.         the most flexible way to give users control about this option and
  3632.         to help them working with their preferred programming environment
  3633.         and development tools.
  3634.  
  3635.         CFTNBASE, CSTNBASE, CXTNBASE:
  3636.         These environment variables can be used to specify  the  name  of
  3637.         the  database.  Similar  to  the  editor  environment  variables,
  3638.         CFTNBASE and CSTNBASE are related to CFTN and CSTN  and  CXTNBASE
  3639.         is  used for both.  For example,  to specify the database 'proj1'
  3640.         located in directory 'd:\develop\projects' type
  3641.  
  3642.              SET CFTNBASE=d:\develop\projects\proj1
  3643.              SET CSTNBASE=d:\develop\projects\proj1
  3644.  
  3645.         for a separate definition or
  3646.  
  3647.              SET CXTNBASE=d:\develop\projects\proj1
  3648.  
  3649.         for a common definition of the database name.
  3650.  
  3651.  
  3652.         COMMAND LINE EXAMPLES
  3653.  
  3654.  
  3655.  
  3656.  
  3657.  
  3658.  
  3659.  
  3660.                                      - 60 -
  3661.  
  3662.  
  3663.         1)   CFTN *
  3664.         Displays all functions in lexicographical order with their return
  3665.         types,  filenames and line numbers.  Gives a short overview about
  3666.         all functions being found.
  3667.  
  3668.         2)   CSTN -e *
  3669.         Edit  all data types in lexicographical order,  use default or by
  3670.         environment variable CSTNEDIT or CXTNEDIT defined editor.
  3671.  
  3672.         3)   CFTN -fproject1 -Evde -e main
  3673.         Search database named 'project1' for  function  'main'  and  edit
  3674.         with editor 'vde'.
  3675.  
  3676.         4)   CSTN -b "union REGS"
  3677.         Search  for  data  type 'union REGS' and display,  if found,  the
  3678.         filename and line number
  3679.  
  3680.         5)   CSTN -e -E"q %s -n%d" -fcft tmbuf
  3681.         Search database 'cft' for data type 'tmbuf' and invoke, if found,
  3682.         the editor 'q' (QEDIT 2.1/3.0) with the filename and line number
  3683.  
  3684.  
  3685.         SEARCHING INSIDE BRIEF (Version 3.0)
  3686.  
  3687.         This feature is one of the most  powerful  enhancements  for  the
  3688.         BRIEF  editor  and offers the user full control over the complete
  3689.         source code of software projects no matter how big they  are  and
  3690.         how  many  files  they include.  It extends the BRIEF editor to a
  3691.         comfortable hypertext source code browser and locator system. The
  3692.         browser allows its  user  to  find  and  read  various  important
  3693.         program constructs like functions and data types in several files
  3694.         simultaneously and moving between them. The complete project with
  3695.         several  source  and  include  files  appears  as  if  it  were a
  3696.         'whole-part'. The browser helps the programmer to learn about the
  3697.         existing program structures and supports him  in  developing  new
  3698.         and  maintaining  existing  code.  The  programmer  can  use  the
  3699.         generated output files CFT.LST or CST.LST (or the one he  created
  3700.         with the -o option) to walk along the hierarchy tree chart and to
  3701.         select  from  there  the  function  or  data  type that should be
  3702.         displayed in detail.
  3703.  
  3704.         The following features are implemented as macros:
  3705.  
  3706.         -    searching for a specific item, tagged or marked
  3707.         -    building menus of all defined items
  3708.         -    building menus of all references to a specific item
  3709.         -    building menus of all processed files
  3710.         -    building menus of all items defined in the current file
  3711.         -    searching for a specific item cross reference number
  3712.         -    changing the database name
  3713.  
  3714.         Every function  and  data  type  can  be  accessed  with  just  a
  3715.         keystroke  by moving the cursor on it ("tagging") and executing a
  3716.         macro to locate the item and zoom  into  the  file  where  it  is
  3717.         defined.  The  user does no longer have to remember the filenames
  3718.  
  3719.  
  3720.  
  3721.                                      - 61 -
  3722.  
  3723.  
  3724.         and locations where the functions and data types are defined  nor
  3725.         does  he  have  to  change  the files,  directories and drives to
  3726.         access the files manually.
  3727.  
  3728.         It is  possible  to  build  interactive  dialog  menus  with  all
  3729.         functions or data types in lexicographical order and to select an
  3730.         item  to  display.  This  is  very useful to get a quick overview
  3731.         about all accessible  functions  and  data  types  of  the  whole
  3732.         project.  It is also possible to build an interactive dialog menu
  3733.         with all filenames in lexicographical order which are  stored  in
  3734.         the database and to select one file to open for edit. Other menus
  3735.         are  available for file contents lists and item cross references.
  3736.         All information to  perform  these  actions  are  stored  in  the
  3737.         databases  generated  by  processing  the  files related with the
  3738.         project.
  3739.  
  3740.         To invoke CFTN and CSTN inside BRIEF,  the macro file CXT.CM must
  3741.         be loaded (with <F9> CXT.CM),  which makes the implemented macros
  3742.         available. These macros are
  3743.  
  3744.              MACRO NAME          KEY ASSIGNMENT (defined in CXTKEYS.CM)
  3745.  
  3746.              cft                 Shift F1
  3747.              cftmenu             Shift F2
  3748.              cftxrefmenu         Shift F3
  3749.              cftxrefmenuagain    Shift F4
  3750.              cftdefmenu          Shift F7
  3751.              cftfilemenu         Shift F8
  3752.              cftfind             Shift F11
  3753.              cftbase             Shift F12
  3754.  
  3755.              cst                 Ctrl F1
  3756.              cstmenu             Ctrl F2
  3757.              cstxrefmenu         Ctrl F3
  3758.              cstxrefmenuagain    Ctrl F4
  3759.              cstdefmenu          Ctrl F7
  3760.              cstfilemenu         Ctrl F8
  3761.              cstfind             Ctrl F11
  3762.              cstbase             Ctrl F12
  3763.  
  3764.              cxtbase             Alt Tab
  3765.              cxtsearchxref       Ctrl Tab
  3766.              cxthelp             <unassigned>
  3767.  
  3768.         This macro key assignment list is also available within BRIEF  as
  3769.         a  help  screen which can be invoked by the macro 'cxthelp'.  The
  3770.         CXT help information is not part of the BRIEF help system because
  3771.         this would need modifications of the original BRIEF help files.
  3772.  
  3773.         Instead of loading the file CXT.CM and  typing  the  macro  names
  3774.         manually,  you  can load the macro file CXTKEYS.CM which performs
  3775.         automatic loading of the CXT.CM file if any of the  above  listed
  3776.         macros  is invoked with a hot-key.  To simplify working with this
  3777.         package,  the CXTKEYS.CM macro file also contains key assignments
  3778.         for  the  macros.  These  hot-keys  offer  a  "point  and  shoot"
  3779.         hypertext like feeling. The macro source file CXTKEYS.CB contains
  3780.  
  3781.  
  3782.                                      - 62 -
  3783.  
  3784.  
  3785.         the source code for CXTKEYS.CM so  that  you  are  able  to  make
  3786.         changes  like  the  key assignments for your personal needs or to
  3787.         move the initialization function to the BRIEF start-up macro file
  3788.         (For  further  information  about  BRIEF  macros  see  the  BRIEF
  3789.         manuals).  To  load  these  macros  and to execute CFTN and CSTN,
  3790.         which are invoked from inside BRIEF, be sure to set the directory
  3791.         path correctly. It is also necessary to allow access to the macro
  3792.         file DIALOG.CM which  contains  the  functions  for  dialog  menu
  3793.         building and processing.
  3794.  
  3795.         A  search  can be started by simply moving the cursor on the item
  3796.         to search for or by marking a block with the item  (necessary  if
  3797.         search pattern contains more than one word like 'struct xyz') and
  3798.         then running one of the following macros (or press hot-keys):
  3799.  
  3800.              <F10> cft                     (function search)
  3801.              <F10> cst                     (data type search)
  3802.  
  3803.         It  is  also  possible to type the name of the item to search for
  3804.         manually. To do this you must run one of the following macros:
  3805.  
  3806.              <F10> cftfind <item>          (function search)
  3807.              <F10> cstfind <item>          (data type search)
  3808.  
  3809.         If the  search  was  successful,  a  new  window  with  the  file
  3810.         containing  the item will be opened and the cursor will be placed
  3811.         at the line where the item is located.  If  inconsistencies  have
  3812.         been detected,  the user will be informed.  If the requested item
  3813.         or the source file containing the item is not  found,  a  message
  3814.         will be given. The macros for building the function and data type
  3815.         dialog menu are
  3816.  
  3817.              <F10> cftmenu                 (function menu)
  3818.              <F10> cstmenu                 (data type menu)
  3819.  
  3820.         You  can  scroll  through  the  entries  and select an item which
  3821.         should be displayed.  To access databases other than the  default
  3822.         ones, there are two ways to change the base names:
  3823.  
  3824.         1)   Set the environment variables CFTNBASE, CSTNBASE or CXTNBASE
  3825.              (see  description  above).  By loading the macro file CXT.CM
  3826.              these variables will be used for initialization.
  3827.  
  3828.         2)   To change the base names from inside BRIEF,  there are three
  3829.              macros  to do this.  They overwrite the initial values given
  3830.              by the environment variables:
  3831.  
  3832.              <F10> cftbase     change base name for function search
  3833.              <F10> cstbase     change base name for data type search
  3834.              <F10> cxtbase     change both CFT and CST base name
  3835.  
  3836.         With these features it is possible to set default values for  the
  3837.         database  files  or to change between different databases without
  3838.         leaving BRIEF which gives the user a maximum of flexibility.  You
  3839.         can  display  a menu list with all source files being scanned for
  3840.         the database by typing
  3841.  
  3842.  
  3843.                                      - 63 -
  3844.  
  3845.  
  3846.  
  3847.              <F10> cftfilemenu             (CFT file menu)
  3848.              <F10> cstfilemenu             (CST file menu)
  3849.  
  3850.         With this feature you can get a quick overview  about  all  files
  3851.         related with the database.  Other menu driven options concern the
  3852.         displaying of all cross references to a specific item (see  macro
  3853.         'cst' for information about marking) with the macros
  3854.  
  3855.              <F10> cftxrefmenu             (CFT cross reference menu)
  3856.              <F10> cftxrefmenuagain        (show previous menu again)
  3857.              <F10> cstxrefmenu             (CST cross reference menu)
  3858.              <F10> cstxrefmenuagain        (show previous menu again)
  3859.  
  3860.         and  the displaying of a file contents list for the actual source
  3861.         file with the macros
  3862.  
  3863.              <F10> cftdefmenu              (CFT file menu)
  3864.              <F10> cstdefmenu              (CST file menu)
  3865.  
  3866.         To search for the first appearance of a specific cross  reference
  3867.         number like '(123)' in a CFT or CST output listing file, move the
  3868.         cursor to the reference number and type
  3869.  
  3870.              <F10> cxtsearchxref           (search cross reference)
  3871.  
  3872.         The macro extracts the complete number and searches for its first
  3873.         occurrence  by  starting  from  the beginning of the output file.
  3874.         With this macro you can move quickly from any  reference  to  its
  3875.         initial description.
  3876.  
  3877.         All  the above described macro functions are defined in the BRIEF
  3878.         macro file CXT.CB. These macros make extensive use of the several
  3879.         options of CFTN  resp.  CSTN,  which  are  described  earlier  in
  3880.         detail.
  3881.  
  3882.  
  3883.         SEARCHING INSIDE QEDIT (2.1 and 3.0)
  3884.  
  3885.         The  popular  shareware  editor  QEDIT with its macro programming
  3886.         capabilities allows,  like the BRIEF  editor,  the  searching  of
  3887.         functions  and  data types from inside the editor.  The following
  3888.         examples for QEDIT macros act, with slight limitations,  like the
  3889.         BRIEF macros 'cft' and 'cst':
  3890.  
  3891.         CFT function searching, assigned to <SHIFT F9>:
  3892.  
  3893.         #f9  MacroBegin  MarkWord Copy Dos 'cftn -b ' Paste '>tmp' Return
  3894.              Return  EditFile  'tmp'  Return  AltWordSet  MarkWord   Copy
  3895.              DefaultWordSet  EditFile  Paste Return EditFile 'tmp' Return
  3896.              EndLine CursorLeft  MarkWord  Copy  Quit  NextFile  GotoLine
  3897.              Paste Return
  3898.  
  3899.  
  3900.  
  3901.  
  3902.  
  3903.  
  3904.                                      - 64 -
  3905.  
  3906.  
  3907.         CST data type searching, assigned to <SHIFT F10>:
  3908.  
  3909.         #f10 MacroBegin  MarkWord Copy Dos 'cstn -b ' Paste '>tmp' Return
  3910.              Return  EditFile  'tmp'  Return  AltWordSet  MarkWord   Copy
  3911.              DefaultWordSet  EditFile  Paste Return EditFile 'tmp' Return
  3912.              EndLine CursorLeft  MarkWord  Copy  Quit  NextFile  GotoLine
  3913.              Paste Return
  3914.  
  3915.         These   QEDIT   macro   definitions   can   be  placed  into  the
  3916.         'qconfig.dat' configuration file and added to  'q.exe'  with  the
  3917.         'qconfig.exe' configuration utility (For additional details about
  3918.         QEDIT  macro  programming  see the QEDIT documentation).  The two
  3919.         macros perform the following  actions:  mark  the  current  word,
  3920.         execute  the CFTN or CSTN database search for the marked word via
  3921.         dos and redirect the output to file 'tmp',  read target  filename
  3922.         from 'tmp' and open target file,  read line number from 'tmp' and
  3923.         go to the selected line.
  3924.  
  3925.         These macros are working almost similar to those used from BRIEF,
  3926.         but they have some limitations in their functionality due to  the
  3927.         limited capabilities of the QEDIT macro programming language:
  3928.  
  3929.         -    there is no error check for a correct cursor location,
  3930.         -    the  searched  item must always be a single word like 'main'
  3931.              or 'size_t',  a combined pattern like 'struct iobuf'  cannot
  3932.              be searched,
  3933.         -    there  is  no  error  check  if the search was successful or
  3934.              failed or the database is not up-to-date,
  3935.         -    if the target file is the same as that from which the search
  3936.              started and other additional files are also open (QEDIT ring
  3937.              buffer), probably a wrong file will be accessed,
  3938.         -    the name of the database cannot be changed, the searches are
  3939.              performed either with the default database or those  defined
  3940.              by the environment variables.
  3941.  
  3942.  
  3943.         SEARCHING INSIDE MicroEMACS (Version 3.11, DOS & WINDOWS)
  3944.  
  3945.         The latest editor which is now supported with macros for database
  3946.         access is MicroEMACS 3.11. The macro file is named CXT_ME.CMD and
  3947.         should  be  place  in  the MircoEMACS directory.  This macro file
  3948.         works with the DOS and the WINDOWS version of MicroEMACS 3.11.
  3949.  
  3950.         The following macros are available:
  3951.  
  3952.         -    cft       function search for tagged item
  3953.         -    cst       data type search for tagged item
  3954.         -    cftmark   function search for marked item
  3955.         -    cstmark   data type search for marked item
  3956.         -    cftfind   function search for user defined item
  3957.         -    cstfind   data type search for user defined item
  3958.         -    cftfile   list of all CFT files
  3959.         -    cstfile   list of all CST files
  3960.         -    cftbase   set CFT database name
  3961.         -    cstbase   set CST database name
  3962.         -    cxtbase   set both CFT and CST database name
  3963.  
  3964.  
  3965.                                      - 65 -
  3966.  
  3967.  
  3968.  
  3969.         They can be invoked by loading the macro file CXT_ME.CMD with
  3970.  
  3971.              ESC CTRL+S CXT_ME.CMD
  3972.  
  3973.         and running the macro with
  3974.  
  3975.              ESC CTRL+E <macro name>
  3976.  
  3977.         If the macros are used with the MicroEMACS WINDOWS  version,  you
  3978.         may  have  to  change the DOSEXEC.PIF file,  which is part of the
  3979.         MicroEMACS  3.11  distribution  package.  During  the  CXT  macro
  3980.         execution,  the  shell command may stop after execution and waits
  3981.         for  the  <return>  key  pressed  to  continue.   To  avoid  this
  3982.         interruption,  you  can  enable  it  by  editing the PIF file and
  3983.         select "Close window after execution".  The environment variables
  3984.         CFTNBASE,  CSTNBASE  and  CXTNBASE are used in the same way as in
  3985.         the BRIEF version.  Key-assignments to macro procedure names  are
  3986.         not  performed,  if you prefer hot-keys,  you are free to do this
  3987.         for yourself.
  3988.  
  3989.         In the MicroEMACS WINDOWS version,  however,  the user accessible
  3990.         macros  can be integrated into the "Miscellaneous" pull-down menu
  3991.         (thanks to  the  incredible  macro  programming  capabilities  of
  3992.         MicroEMACS!).   To  view  the  generated  output  file  with  its
  3993.         semigraphic frames,  change the font type and select for  example
  3994.         the  'TERMINAL'  font  from  the  OEM  font  list  which supports
  3995.         semigraphic characters.
  3996.  
  3997.  
  3998.  
  3999.  
  4000.  
  4001.  
  4002.  
  4003.  
  4004.  
  4005.  
  4006.  
  4007.  
  4008.  
  4009.  
  4010.  
  4011.  
  4012.  
  4013.  
  4014.  
  4015.  
  4016.  
  4017.  
  4018.  
  4019.  
  4020.  
  4021.  
  4022.  
  4023.  
  4024.  
  4025.  
  4026.                                      - 66 -
  4027.  
  4028.  
  4029.         11   IMPROVING EXECUTION SPEED
  4030.  
  4031.         CFT and CST are disk storage based programs  because  the  source
  4032.         and  include  files,  the  intermediate  precompiler file and the
  4033.         output file must be read from and  written  to  hard  disk.  This
  4034.         means that the execution speed of CFT and CST depends at first on
  4035.         the  speed  of  the physical storage medium and not (only) on the
  4036.         speed of the CPU.  There are several ways to improve the  program
  4037.         performance:
  4038.  
  4039.         -    install a RAM-disk and
  4040.              a)   start  CFT  and CST from there so that the intermediate
  4041.                   file and the resulting output file will be stored there
  4042.                   (but don't forget to copy the output file to  the  hard
  4043.                   disk before power-off), or
  4044.              b)   use  the  -v  option  to  redirect only the precompiler
  4045.                   output file (scanner input file) to the  RAM-disk  from
  4046.                   anywhere  the  program is started (the RAM-disk must be
  4047.                   large enough to hold  the  largest  possible  temporary
  4048.                   file, otherwise a disk-write error will occur),
  4049.         -    use a hard disk cache program like SmartDrive,  HyperDisk or
  4050.              PC-Cache,
  4051.         -    use a faster hard disk,
  4052.         -    and finally, of course, use a faster and more powerful CPU.
  4053.  
  4054.         The most effective combination is option -v with  a  RAM-disk  as
  4055.         destination  path and hard disk caching together with a fast hard
  4056.         disk drive. If the disk cache is large enough to hold most of the
  4057.         frequently called include files, the execution speed is about 2.5
  4058.         to 3 times faster than without.  This is a  significant  speed-up
  4059.         especially  for  projects  with  a large number of files and many
  4060.         included files in each source file.
  4061.  
  4062.         During program execution with preprocessing (option -P),  most of
  4063.         the time will be consumed to preprocess the given input files and
  4064.         the related include files and to generate the preprocessor output
  4065.         file.  The scanning for functions (CFT) or data types (CST) takes
  4066.         only a small amount of time. The function/data type relations are
  4067.         computed while the output is generated and written to disk, there
  4068.         is no precomputing necessary.
  4069.  
  4070.         The function  for  critical  call  path/nesting  level  detection
  4071.         depends  only on the number of functions or structures and not on
  4072.         the call/declaration nesting complexity. The execution time grows
  4073.         linear with the number of items (functions/structures) to process
  4074.         and is very fast!
  4075.  
  4076.         Be aware of the fact that the processing of  a  large  number  of
  4077.         files  can  take  quite  a  long time (from several minutes up to
  4078.         hours on lower performance machines!),  especially if  option  -P
  4079.         for preprocessing is enabled.
  4080.  
  4081.         The  generation  of  the output file and writing to disk can also
  4082.         take some time if the number of items to display is large and the
  4083.         nesting structure is complex or if there is  no  cross  reference
  4084.         option  enabled  (see -x and -r for further information).  If the
  4085.  
  4086.  
  4087.                                      - 67 -
  4088.  
  4089.  
  4090.         number of items and source files is very large,  one of the  most
  4091.         time  consuming  options is the function/data type file reference
  4092.         (option -z).  The writing  and  reading  of  the  database  files
  4093.         (options  -G and -g) takes also some time due to the large number
  4094.         of different information.
  4095.  
  4096.         Don't panic if there seems to be no  disk  access  for  a  longer
  4097.         time,  the  reason  is  just  that  there  may  be time consuming
  4098.         computations and that the output will be buffered  internally  to
  4099.         reduce  the  number  of  disk accesses and therefore speed up the
  4100.         output!
  4101.  
  4102.         To speed up the SXTWIN program execution you  should  switch  off
  4103.         the  filename  and line number info (Analysis menu) to avoid time
  4104.         consuming screen updates.  Additionally the program  can  be  run
  4105.         iconized, this also avoids sreen updates.
  4106.  
  4107.         For  more  detailed  information about the program efficiency see
  4108.         appendix 4.
  4109.  
  4110.  
  4111.  
  4112.  
  4113.  
  4114.  
  4115.  
  4116.  
  4117.  
  4118.  
  4119.  
  4120.  
  4121.  
  4122.  
  4123.  
  4124.  
  4125.  
  4126.  
  4127.  
  4128.  
  4129.  
  4130.  
  4131.  
  4132.  
  4133.  
  4134.  
  4135.  
  4136.  
  4137.  
  4138.  
  4139.  
  4140.  
  4141.  
  4142.  
  4143.  
  4144.  
  4145.  
  4146.  
  4147.  
  4148.                                      - 68 -
  4149.  
  4150.  
  4151.         12   TROUBLE SHOOTING
  4152.  
  4153.         This section contains information about problems and the  reasons
  4154.         which  may  occur during the use of SXT programs.  It is strictly
  4155.         recommended that users should read the complete documentation  to
  4156.         have  an  overview about the features before they start using the
  4157.         programs and run into  any  unexpected  troubles.  See  also  the
  4158.         chapter    about   'PROGRAM   LIMITATIONS'   and   the   document
  4159.         'PROBLEMS.DOC'.
  4160.  
  4161.         UNEXPECTED RESULTS WHILE RUNNING THE SXT COMMAND LINE  TEXT  MODE
  4162.         VERSIONS UNDER WINDOWS 3.1
  4163.         The 386 versions cannot run under Windows 3.1, they are using the
  4164.         CPU  exclusive and can therefore not co-exist with Windows,  only
  4165.         the real mode versions can. In Windows enhanced mode (virtual 386
  4166.         mode),  the real  mode  versions  cannot  run  simultaneously  in
  4167.         several  independent  DOS-windows if they are working in the same
  4168.         directory or  use  the  same  temporary  directory,  because  the
  4169.         temporary  intermediate  files  may  have the same names and will
  4170.         conflict due to multiple concurrent accesses to  them.  This  may
  4171.         also happen if the same files are scanned or included. The use of
  4172.         SHARE.EXE  is  highly  recommended  to  catch  such  file  access
  4173.         conflicts,   see  your  DOS  manual  for  information  about  the
  4174.         installation of SHARE.
  4175.  
  4176.         MICROEMACS  FOR  WINDOWS SEEMS TO HANG DURING DATABASE ACCESS AND
  4177.         DOES NOT RETURN
  4178.         The reason is usually quite simple: The shell call to DOS through
  4179.         DOSEXEC.PIF waits for a keystroke to continue  execution  and  to
  4180.         return  to WINDOWS.  You may change this behaviour by editing the
  4181.         DOSEXEC.PIF   file   (see   MicroEMACS   section   for    further
  4182.         information).
  4183.  
  4184.         A PROGRAM CANNOT BE EXECUTED
  4185.         The  program  path  is  not specified in the environment variable
  4186.         PATH,  the programs  are  not  yet  installed  in  the  specified
  4187.         directory,  attempt  to  start  a 386 protected mode version on a
  4188.         80286 (or lower) computer.
  4189.  
  4190.         EXECUTION STOPPED WITH MESSAGE "OUT OF MEMORY"
  4191.         An  attempt  to  allocate  memory  has  failed.   Try  to  remove
  4192.         unnecessary memory resident TSR programs and/or use the protected
  4193.         mode versions if you have an 386/486. If this message happens for
  4194.         the protected mode versions,  there is not enough free disk space
  4195.         for the swap file. Set the temporary directory,  defined by 'TMP'
  4196.         resp.   'TEMP'  environment  variables,   to  another  drive,  if
  4197.         possible.
  4198.  
  4199.         WRITING THE OUTPUT FILE TAKES A LONG TIME
  4200.         A large number of information must be handled, option -x or -r is
  4201.         not set and so the output calltree is very large, slow CPU and/or
  4202.         harddisk.  Use option -v to  redirect  intermediate  files  to  a
  4203.         faster RAM-disk (if such is present).
  4204.  
  4205.  
  4206.  
  4207.  
  4208.  
  4209.                                      - 69 -
  4210.  
  4211.  
  4212.         THE RESULTING OUTPUT IS DEEPLY NESTED AND EXCEEDS THE SCREEN SIZE
  4213.         Two  reasons: Use the -r or -x option if not already specified or
  4214.         the source code/data types are indeed deeply nested.
  4215.  
  4216.         THE BRIEF MACROS CANNOT BE EXECUTED
  4217.         The macro file is not loaded, other macros with the same names or
  4218.         assigned keys already exist.
  4219.  
  4220.         THE BRIEF OR MICROEMACS MACROS CANNOT BE LOADED
  4221.         The path to the  macro  file  location  must  be  specified  when
  4222.         loading the macros,  if they are not in the default directory for
  4223.         the editor.
  4224.  
  4225.         THE BRIEF MACROS DO NOT FIND ANY FUNCTIONS OR DATA TYPES
  4226.         There is no access to CFTN,  CSTN,  DFTN (...),  due to incorrect
  4227.         path  specification,  no  database  is  present,  the path to the
  4228.         database files is incorrect, the database name is incorrect.
  4229.  
  4230.         THE BYTE OFFSET CALCULATION FILE "CST_OFFS.C" CANNOT BE COMPILED
  4231.         Several reasons: Necessary data types or include  files  are  not
  4232.         specified or the CST processing was done with include files other
  4233.         than  those being used for compiling.  If the number of data type
  4234.         information is too large, some compilers cannot compile the large
  4235.         number of statements in a single file generated from CST ('out of
  4236.         heap space',  'code segment too large'  or  other  messages  like
  4237.         that).  In  that case you may have to split the file into several
  4238.         smaller files or reduce the number of data types to display.
  4239.  
  4240.         LOCATING ITEMS IN THE BRIEF EDITOR POINTS TO WRONG PLACES
  4241.         Searching items from within the  BRIEF  editor  points  to  wrong
  4242.         lines,  the requested item is not present there or the file seems
  4243.         to be corrupted.  This can have several reasons: The file is  not
  4244.         up-to-date  and has been changed since the database generation so
  4245.         that the line references are no longer valid.  Another reason can
  4246.         be that the source file has explicit #line numbers as it is usual
  4247.         for  files  produced by source code generators like YACC/BISON or
  4248.         LEX/FLEX.  A third  reason  may  be  that  the  source  file  was
  4249.         generated  on an UNIX system and has therefore only LF instead of
  4250.         CR+LF as end-of-line delimiter so that BRIEF cannot  display  the
  4251.         file correctly, the file seems to be written in a single line. If
  4252.         possible  convert  such files to DOS text format with UNIX2DOS or
  4253.         other utilities.
  4254.  
  4255.         THE SOURCE ANALYSIS WITH THE SXT WINDOWS VERSIONS IS VERY SLOW
  4256.         Windows adds a lot of overhead to the program execution and there
  4257.         is no possibility to avoid this,  but there are three  things  to
  4258.         speed up the SXTWIN programs.  First, switch off the filename and
  4259.         line number info (Analysis menu) to avoid time  consuming  screen
  4260.         updates.  Second,  if possible,  specify a RAM-disk drive for the
  4261.         temporary files (option -v).  Third,  run the program as an icon,
  4262.         because this also avoids sreen updates.
  4263.  
  4264.  
  4265.  
  4266.  
  4267.  
  4268.  
  4269.  
  4270.                                      - 70 -
  4271.  
  4272.  
  4273.         13   FREQUENTLY ASKED QUESTIONS (FAQ)
  4274.  
  4275.         ARE THERE ANY RESTRICTIONS IN THE USE OF THE ANALYSIS RESULTS?
  4276.         No  restrictions  for REGISTERED users,  they can use the results
  4277.         for all purposes like program documentation, customer information
  4278.         or debugging as long as a notice about the name and copyright  of
  4279.         the used SXT program is given.
  4280.  
  4281.         WHY  IS  NO  OS/2  IPF  SOURCE  CODE  FOR  OS/2 INFORMATION FILES
  4282.         GENERATED?
  4283.         The OS/2 IPF functionality,  comparable with the MS-Windows  Help
  4284.         system,   has  limitations  which  are  not  acceptable  for  SXT
  4285.         programs.  According to the OS/2 3.0 online help information,  it
  4286.         is  not possible to generate a single IPF source file larger than
  4287.         64K  and  a  single  source  line  cannot  have  more  than   255
  4288.         characters.  Both  limits  are  regularly  exceeded  by  the  SXT
  4289.         programs.
  4290.  
  4291.         WHY ARE SEVERAL DATABASE FILES FOR EVERY PROJECT GENERATED?
  4292.         Separating  the  analysis  items  (identifier  names,  filenames,
  4293.         relationships,  ...)  of one project into several closely related
  4294.         database files  is  the  best  way  to  achieve  minimum  storage
  4295.         requirements and to optimise disk usage.  This way of storage has
  4296.         no redundancies compared to storage in a single database file.
  4297.  
  4298.         WHY IS THERE NO CROSS REFERENCE FOR VARIABLES INCLUDED?
  4299.         This would  need  much  additional  memory  and  slows  down  the
  4300.         analysis  process.  There would also be a lot of multiple defined
  4301.         names in different contexts to be managed if  several  files  are
  4302.         analysed. A lot of tools exist which perform this task quite good
  4303.         e.g.  the  integrated  compiler environments or other source code
  4304.         analysers.
  4305.  
  4306.         WHY ARE CFT AND CST NOT COMBINED IN ONE PROGRAM?
  4307.         Historical and practical reasons: the CFT development was started
  4308.         before CST and both programs are optimised for their own  special
  4309.         purposes.  Combining them would complicate them and slow down the
  4310.         analysis process. Also the memory requirements would grow.
  4311.  
  4312.  
  4313.  
  4314.  
  4315.  
  4316.  
  4317.  
  4318.  
  4319.  
  4320.  
  4321.  
  4322.  
  4323.  
  4324.  
  4325.  
  4326.  
  4327.  
  4328.  
  4329.  
  4330.  
  4331.                                      - 71 -
  4332.  
  4333.  
  4334.         14   REFERENCES
  4335.  
  4336.         Brian  W.  Kernighan,  Dennis  M.  Ritchie:  "The  C  Programming
  4337.         Language", Prentice Hall, Englewood Cliffs, Second Edition 1988
  4338.  
  4339.         Samuel P.  Harbison,  Guy L. Steele Jr.: "C: A Reference Manual",
  4340.         Prentice Hall, Englewood Cliffs, Third Edition 1991
  4341.  
  4342.         Bjarne    Stroustrup:    "The    C++    Programming    Language",
  4343.         Addison-Wesley, Second Edition 1992
  4344.  
  4345.         Bjarne   Stroustrup:   "The   Design   and   Evolution  of  C++",
  4346.         Addison-Wesley, 1994
  4347.  
  4348.         Margaret  A.   Ellis,   Bjarne  Stroustrup:  "The  Annotated  C++
  4349.         Reference Manual" (ARM), Addison-Wesley, Second Edition 1991
  4350.  
  4351.         "Rationale for American National Standard for Information Systems
  4352.         - Programming Language C" (can be obtained via anonymous FTP from
  4353.         ftp.uu.net in '/doc/standards/ansi/X3.159-1989/ratinale.PS.Z')
  4354.  
  4355.         "Working  Paper  for  Draft  Proposed  International Standard for
  4356.         Information Systems  -  Programming  Language  C++",  AT&T,  ANSI
  4357.         committee X3J16, ISO working group WG21, January 28, 1993
  4358.  
  4359.         "Working  Paper  for  Draft  Proposed  International Standard for
  4360.         Information Systems  -  Programming  Language  C++",  AT&T,  ANSI
  4361.         committee X3J16, ISO working group WG21, April 28, 1995
  4362.  
  4363.         Bjarne Stroustrup, Keith Gorlen, Phil Brown, Dennis Mancl, Andrew
  4364.         Koenig: "UNIX System V - AT&T C++ Language System,  Release 2.1 -
  4365.         Selected Readings", AT&T, 1989
  4366.  
  4367.         Goldberg,  A.: "Programmer as Reader",  IEEE Software,  September
  4368.         1987
  4369.  
  4370.         L.W.  Cannon,  R.A.  Elliot,  L.W.  Kirchhoff,  J.H. Miller, J.M.
  4371.         Milner, R.W. Mitze, E.P. Schan, N.O. Whittington, H. Spencer,  D.
  4372.         Keppel,  M.  Brader:  "Recommended C Style and Coding Standards",
  4373.         Technical Report, in the Public Domain,  Revision 6.0,  July 1991
  4374.         (revised  and  updated  version  of  the  'AT&T Indian Hill style
  4375.         guide',  can be obtained via anonymous FTP from cs.washington.edu
  4376.         in '~ftp/pub/cstyle.tar.Z')
  4377.  
  4378.         A.  Dolenc,  A. Lemmke, D. Keppel, G.V. Reilly: "Notes on Writing
  4379.         Portable Programs in C", Technical Report,  in the Public Domain,
  4380.         Revision 8, November 1990 (can be obtained via anonymous FTP from
  4381.         cs.washington.edu in '~ftp/pub/cport.tar.Z')
  4382.  
  4383.         M.   Henricson,  E.  Nyquist:  "Programming  in  C++,  Rules  and
  4384.         Recommendations",   Technical  Report,   in  the  Public  Domain,
  4385.         Ellemtel  Telecommunication Systems Laboratories,  Alvsjo/Sweden,
  4386.         Document No. M 90 0118 Uen, Rev. C (can be obtained via anonymous
  4387.         FTP from various sites as 'rules.ps.Z' or 'c++rules.ps.Z')
  4388.  
  4389.         H. Wehnes: "FORTRAN 77", 3. Auflage, Carl Hanser Verlag, 1984
  4390.  
  4391.  
  4392.                                      - 72 -
  4393.  
  4394.  
  4395.  
  4396.         H.   Sigl:  "dBase/Foxbase/Clipper  -  Globalreferenz",   Addison
  4397.         Wesley, 1989
  4398.  
  4399.         "A  Beginner's  Guide  to  HTML",  electronically  available from
  4400.         'http://www.ncsa.uiuc.edu/General/Internet/WWW/HTMLPrimer.html'
  4401.  
  4402.  
  4403.         Compiler reference manuals and related  documentations  (language
  4404.         references, language implementations and extensions):
  4405.  
  4406.         -    Microsoft C 5.1
  4407.         -    Microsoft C 6.0
  4408.         -    Microsoft C/C++ 7.0
  4409.         -    Microsoft Visual C++ 1.5 Professional
  4410.         -    Microsoft C/C++ for Windows NT (Beta Release 3/93)
  4411.         -    Microsoft Visual C++ 1.0 for Windows NT (Beta Release 6/93)
  4412.         -    Microsoft Visual C++ 1.1 for Windows NT
  4413.         -    Microsoft C for SCO UNIX System V Rel. 3.2
  4414.         -    Microsoft Macro Assembler MASM 5.1
  4415.         -    Borland Turbo C++ 1.0
  4416.         -    Borland C++ 2.0
  4417.         -    Borland C++ 3.1
  4418.         -    Borland C++ 1.0 for OS/2
  4419.         -    Borland Turbo Assembler TASM 2.0
  4420.         -    Intel 80860 Metaware High C i860 APX (UNIX-hosted)
  4421.         -    Intel 80960 C-Compiler (ic960, ec960)
  4422.         -    Intel 80960 Assembler (asm960)
  4423.         -    Watcom C/C++ 10.0a
  4424.         -    GNU-960 Tools (UNIX-hosted)
  4425.         -    GNU-C   Compiler   2.2.2/  2.4.5/  2.5.7/  2.6.3  (C,   C++,
  4426.              Objective-C), GNU-C DOS and OS/2 ports (DJGPP, EMX)
  4427.         -    GNU Assembler
  4428.         -    AT&T C++ 2.1 CFRONT (C++  to  C  translator)  for  SCO  UNIX
  4429.              System V Rel. 3.2
  4430.         -    IBM  C-Compilers  (CC,  XLC)  for IBM RS 6000 RISC stations,
  4431.              AIX 3.15
  4432.         -    HP C-Compilers (CC,  C89) for HP Apollo 9000 RISC  stations,
  4433.              HP-UX 9.0
  4434.         -    SUN SunOS 4.1 C-Compiler
  4435.         -    Digital Equipment Corporation (DEC) VAX C
  4436.         -    Digital Equipment Corporation (DEC) VAX FORTRAN
  4437.         -    Ashton Tate dBase III plus
  4438.  
  4439.  
  4440.  
  4441.  
  4442.  
  4443.  
  4444.  
  4445.  
  4446.  
  4447.  
  4448.  
  4449.  
  4450.  
  4451.  
  4452.  
  4453.                                      - 73 -
  4454.  
  4455.  
  4456.         15   TRADEMARKS
  4457.  
  4458.         All  brand  or  product  names  are trademarks (TM) or registered
  4459.         trademarks (R) of their respective owners.
  4460.  
  4461.         The following  products  and  names  are  Copyright  (C)  Juergen
  4462.         Mueller (J.M.), all rights reserved world-wide:
  4463.  
  4464.              CXT (TM) C EXPLORATION TOOLS
  4465.              CFT (TM) C FUNCTION TREE GENERATOR
  4466.              CFTN (TM) C FUNCTION TREE NAVIGATOR
  4467.              CST (TM) C STRUCTURE TREE GENERATOR
  4468.              CSTN (TM) C STRUCTURE TREE NAVIGATOR
  4469.  
  4470.              CXTWIN (TM) C EXPLORATION TOOLS for Windows
  4471.              CFTWIN (TM) C FUNCTION TREE GENERATOR for Winfows
  4472.              CSTWIN (TM) C STRUCTURE TREE GENERATOR for Windows
  4473.  
  4474.              DXT (TM) DBASE EXPLORATION TOOLS
  4475.              DFT (TM) DBASE FUNCTION TREE GENERATOR
  4476.              DFTN (TM) DBASE FUNCTION TREE NAVIGATOR
  4477.  
  4478.              DXTWIN (TM) DBASE EXPLORATION TOOLS for Windows
  4479.              DFTWIN (TM) DBASE FUNCTION TREE GENERATOR for Windows
  4480.  
  4481.              FXT (TM) FORTRAN EXPLORATION TOOLS
  4482.              FFT (TM) FORTRAN FUNCTION TREE GENERATOR
  4483.              FFTN (TM) FORTRAN FUNCTION TREE NAVIGATOR
  4484.  
  4485.              FXTWIN (TM) FORTRAN EXPLORATION TOOLS for Windows
  4486.              FFTWIN (TM) FORTRAN FUNCTION TREE GENERATOR for Windows
  4487.  
  4488.              LXT (TM) LISP EXPLORATION TOOLS
  4489.              LFT (TM) LISP FUNCTION TREE GENERATOR
  4490.              LFTN (TM) LISP FUNCTION TREE NAVIGATOR
  4491.  
  4492.              LXTWIN (TM) LISP EXPLORATION TOOLS for Windows
  4493.              LFTWIN (TM) LISP FUNCTION TREE GENERATOR for Windows
  4494.  
  4495.         These packages are part of
  4496.  
  4497.              SXT (TM) SOFTWARE EXPLORATION TOOLS
  4498.              SXTWIN (TM) SOFTWARE EXPLORATION TOOLS for Windows
  4499.  
  4500.         which  provide  a  similar  set of functionalities for the source
  4501.         code analysis of different programming languages.
  4502.  
  4503.         See PRODUCT.DOC for a complete overview of the SXT  packages  and
  4504.         the different supported platforms.
  4505.  
  4506.  
  4507.  
  4508.  
  4509.  
  4510.  
  4511.  
  4512.  
  4513.  
  4514.                                      - 74 -
  4515.  
  4516.  
  4517.         APPENDIX 1: C/C++ PRECOMPILER DEFINES
  4518.  
  4519.         The  following list shows the builtin precompiler defines for the
  4520.         supported compiler types (option -T).  It  contains  the  default
  4521.         defines and the optional memory model and architecture defines.
  4522.  
  4523.         Other default compiler defines which are usually declared by some
  4524.         of  the compilers are not automatically defined by the -T option.
  4525.         These are defines  for  compilation  like  WINDOWS,  __WINDOWS__,
  4526.         _Windows,  DLL or __DLL__,  for optimization like __OPTIMIZE__ or
  4527.         __FASTCALL__ or others  like  those  about  target-  (operating-)
  4528.         systems like NT,  MIPS,  UNIX,  unix,  __unix__,  i386, __i386__,
  4529.         GNUDOS, BSD, VMS, USG,  DGUX or hpux.  Other sometimes predefined
  4530.         macros  are  __STRICT_ANSI__ or __CHAR_UNSIGNED__.  If necessary,
  4531.         they can be user defined on the command line with the -D option.
  4532.  
  4533.         The macro name __cplusplus will be defined if  the  command  line
  4534.         option '-C++' is set to enable C++ processing.
  4535.  
  4536.         1. MSC51 (Microsoft C 5.1):
  4537.         Default defines:         MSDOS, M_I86
  4538.         C++ specific defines:    (none)
  4539.         Memory model defines:    M_I86SM, M_I86MM, M_I86CM, M_I86LM,
  4540.                                  M_I86HM
  4541.  
  4542.         2. MSC70 (Microsoft C/C++ 7.0):
  4543.         Default defines:         MSDOS, M_I86, _MSC_VER (= 700)
  4544.         C++ specific defines:    (none)
  4545.         Memory model defines:    M_I86TM, M_I86SM, M_I86MM, M_I86CM,
  4546.                                  M_I86LM, M_I86HM
  4547.  
  4548.         3. MSVC15 (Microsoft Visual C++ 1.5):
  4549.         Default defines:         MSDOS, M_I86, _MSC_VER (= 800)
  4550.         C++ specific defines:    (none)
  4551.         Memory model defines:    M_I86TM, M_I86SM, M_I86MM, M_I86CM,
  4552.                                  M_I86LM, M_I86HM
  4553.  
  4554.         4. MSVCWNT (Microsoft Visual C++ 1.1 for Windows NT):
  4555.         Default defines:         MSDOS, M_I86, _MSC_VER (= 800),
  4556.                                  _M_IX86 (= 300)
  4557.         C++ specific defines:    (none)
  4558.         Memory model defines:    (not necessary)
  4559.  
  4560.         5. TC10 (Borland Turbo C++ 1.0):
  4561.         Default defines:         __MSDOS__, __TURBOC__
  4562.         C++ specific defines:    __TCPLUSPLUS
  4563.         Memory model defines:    __TINY__, __SMALL__, __MEDIUM__,
  4564.                                  __COMPACT_, __LARGE__, __HUGE__
  4565.  
  4566.         6. BC20 (Borland C++ 2.0):
  4567.         Default defines:         __MSDOS__, __BORLANDC__ (= 0x0200),
  4568.                                  __TURBOC__ (= 0x0297)
  4569.         C++ specific defines:    __BCPLUSPLUS__ (= 0x0200),
  4570.                                  __TCPLUSPLUS__ (= 0x0200)
  4571.         Memory model defines:    __TINY__, __SMALL__, __MEDIUM__,
  4572.                                  __COMPACT_, __LARGE__, __HUGE__
  4573.  
  4574.  
  4575.                                      - 75 -
  4576.  
  4577.  
  4578.  
  4579.         7. BC31 (Borland C++ 3.1):
  4580.         Default defines:         __MSDOS__, __BORLANDC__ (= 0x0410),
  4581.                                  __TURBOC__ (= 0x0410)
  4582.         C++ specific defines:    __BCPLUSPLUS__ (= 0x0310),
  4583.                                  __TCPLUSPLUS__ (= 0x0310)
  4584.         Memory model defines:    __TINY__, __SMALL__, __MEDIUM__,
  4585.                                  __COMPACT_, __LARGE__, __HUGE__
  4586.  
  4587.         8. BC10OS2 (Borland C++ 1.0 for OS/2):
  4588.         Default defines:         __OS2__, __BORLANDC__ (= 0x0400),
  4589.                                  __TURBOC__ (= 0x0400)
  4590.         C++ specific defines:    __BCPLUSPLUS__ (= 0x0320),
  4591.                                  __TCPLUSPLUS__ (= 0x0320),
  4592.                                  __TEMPLATES__
  4593.         Memory model defines:    (not necessary)
  4594.  
  4595.         9. GNU (GNU C 2.2.2):
  4596.         Default defines:         __GNUC__ (= 2)
  4597.         C++ specific defines:    __GNUG__ (= 2)
  4598.         Memory model defines:    (not necessary)
  4599.  
  4600.         10. I960 (Intel iC960 3.0):
  4601.         Default defines:         __i960
  4602.         C++ specific defines:    (none)
  4603.         Memory model defines:    (not necessary)
  4604.         Architecture defines:    __i960KA, __i960KB, __i960SA, __i960SB,
  4605.                                  __i960MC, __i960CA
  4606.  
  4607.  
  4608.         USER DEFINED ADAPTATION OF CFT AND CST TO OTHER COMPILERS
  4609.  
  4610.         The  adaptation  of  CFT  and CST to other C/C++ compilers can be
  4611.         done with the -D,  -U and -B options.  First you have to find out
  4612.         which precompiler defines the compiler uses by default or related
  4613.         to   command   line  options.   For  these  information  see  the
  4614.         documentation and help-files for  your  compiler.  The  necessary
  4615.         precompiler defines have to be specified for CFT and CST with -D.
  4616.         Additionally it may be necessary to specify undefines with -U and
  4617.         to declare the basic type size with -B.  The following line shows
  4618.         as an example the necessary options for the  MS  Visual  C++  1.5
  4619.         compiler (large model):
  4620.  
  4621.         -DMSDOS -DM_I86 -DMSC_VER=800 -DM_I86LM -B0,1,2,2,4,4,8,10*4,4
  4622.  
  4623.  
  4624.  
  4625.  
  4626.  
  4627.  
  4628.  
  4629.  
  4630.  
  4631.  
  4632.  
  4633.  
  4634.  
  4635.  
  4636.                                      - 76 -
  4637.  
  4638.  
  4639.         APPENDIX 2: RESERVED C/C++ KEYWORDS
  4640.  
  4641.         The following list shows the keywords being recognised by CFT and
  4642.         CST,   the  standard  C  keywords,   the  C++  keywords  and  the
  4643.         non-standard keywords which are compiler dependent extensions  to
  4644.         the C or C++ language. Standard C keywords are also C++ keywords,
  4645.         always!  The C++ keywords are recognised only if option '-C++' is
  4646.         set, otherwise they are treated as identifiers. This list may not
  4647.         be complete or correct  due  to  upcoming  new  releases  of  the
  4648.         supported  compilers  with  new  extensions  or extensions to the
  4649.         language standard.  C++,  for which till now no  'real'  language
  4650.         standard  exists  (except the de-facto standard,  the AT&T CFRONT
  4651.         implementation),    differs   among   several    implementations,
  4652.         especially for the new introduced exception and template concepts
  4653.         (try,   catch,  throw,  template).  Extensions  to  the  language
  4654.         especially  in  GNU  C  (e.g.  __alignof,  __classof,  interface,
  4655.         signature,  __FUNCTION__,  ...)  or undocumentd features e.g.  in
  4656.         Microsoft C/C++ 7.0 are ignored (even if they are  listed  here).
  4657.         This list may not be complete or correct.
  4658.  
  4659.         KEYWORDS            Standard       MSC TC/BC GNU C/C++
  4660.                             C    C++       7.0 3.0   2.2.2
  4661.  
  4662.         and                      x
  4663.         and_eq                   x
  4664.         asm                 x
  4665.         auto                x
  4666.         bitand                   x
  4667.         bitor                    x
  4668.         bool                     x
  4669.         break               x
  4670.         case                x
  4671.         catch                    x         (x)       x
  4672.         cdecl                              x    x
  4673.         char                x
  4674.         class                    x
  4675.         classof                                      x
  4676.         const               x
  4677.         const_cast               x
  4678.         continue            x
  4679.         default             x
  4680.         delete                   x
  4681.         do                  x
  4682.         double              x
  4683.         dynamic                                      x
  4684.         dynamic_cast             x
  4685.         else                x
  4686.         enum                x
  4687.         except                                       x
  4688.         exception                                    x
  4689.         explicit                 x
  4690.         extern              x
  4691.         false                    x
  4692.         far                                x    x
  4693.         float               x
  4694.         for                 x
  4695.  
  4696.  
  4697.                                      - 77 -
  4698.  
  4699.  
  4700.         fortran                            x    x
  4701.         friend                   x
  4702.         goto                x
  4703.         huge                               x    x
  4704.         if                  x
  4705.         inline                   x
  4706.         int                 x
  4707.         interrupt                          x    x
  4708.         long                x
  4709.         mutable                  x
  4710.         namespace                x
  4711.         near                               x    x
  4712.         new                      x
  4713.         not                      x
  4714.         not_eq                   x
  4715.         operator                 x
  4716.         or                       x
  4717.         or_eq                    x
  4718.         overload                                x    x
  4719.         pascal                             x    x
  4720.         private                  x
  4721.         protected                x
  4722.         public                   x
  4723.         register            x
  4724.         reinterpret_cast         x
  4725.         return              x
  4726.         short               x
  4727.         signed              x
  4728.         sizeof              x
  4729.         static              x
  4730.         static_cast              x
  4731.         struct              x
  4732.         switch              x
  4733.         template                 x
  4734.         this                     x
  4735.         throw                    x
  4736.         true                     x
  4737.         try                      x         (x)       x
  4738.         typedef             x
  4739.         typeid                   x
  4740.         typename                 x
  4741.         typeof                                       x
  4742.         union               x
  4743.         unsigned            x
  4744.         using                    x
  4745.         virtual                  x
  4746.         void                x
  4747.         volatile            x
  4748.         wchar_t                  x
  4749.         while               x
  4750.         xor                      x
  4751.         xor_eq                   x
  4752.  
  4753.  
  4754.  
  4755.  
  4756.  
  4757.  
  4758.                                      - 78 -
  4759.  
  4760.  
  4761.         __alignof                                    x
  4762.         __alignof__                                  x
  4763.         __asm                              x         x
  4764.         __asm__                                      x
  4765.         __attribute                                  x
  4766.         __attribute__                                x
  4767.         __based                            x
  4768.         __cdecl                            x
  4769.         __classof                                    x
  4770.         __classof__                                  x
  4771.         __const                            x         x
  4772.         __const__                                    x
  4773.         __emit                             x
  4774.         __except                           x
  4775.         __export                           x
  4776.         __extension__                                x
  4777.         __far                              x
  4778.         __fastcall                         x
  4779.         __finally                          x
  4780.         __fortran                          x
  4781.         __headof                                     x
  4782.         __headof__                                   x
  4783.         __huge                             x
  4784.         __inline                                     x
  4785.         __inline__                                   x
  4786.         __interrupt                        x
  4787.         __label__                                    x
  4788.         __loadds                           x
  4789.         __near                             x
  4790.         __saveregs                         x
  4791.         __segment                          x
  4792.         __segname                          x
  4793.         __self                             x
  4794.         __signed                                     x
  4795.         __signed__                                   x
  4796.         __stdcall                          x
  4797.         __syscall                          x
  4798.         __try                              x
  4799.         __typeof                                     x
  4800.         __typeof__                                   x
  4801.         __volatile                                   x
  4802.         __volatile__                                 x
  4803.  
  4804.         _asm                               x
  4805.         _based                             x
  4806.         _cdecl                             x
  4807.         _emit                              x
  4808.         _export                            x    x
  4809.         _far                               x
  4810.         _fastcall                          x
  4811.         _fortran                           x
  4812.         _huge                              x
  4813.         _interrupt                         x
  4814.         _loadds                            x    x
  4815.         _near                              x
  4816.         _pascal                            x
  4817.  
  4818.  
  4819.                                      - 79 -
  4820.  
  4821.  
  4822.         _saveregs                          x    x
  4823.         _seg                                    x
  4824.         _segment                           x
  4825.         _segname                           x
  4826.         _self                              x
  4827.  
  4828.  
  4829.  
  4830.  
  4831.  
  4832.  
  4833.  
  4834.  
  4835.  
  4836.  
  4837.  
  4838.  
  4839.  
  4840.  
  4841.  
  4842.  
  4843.  
  4844.  
  4845.  
  4846.  
  4847.  
  4848.  
  4849.  
  4850.  
  4851.  
  4852.  
  4853.  
  4854.  
  4855.  
  4856.  
  4857.  
  4858.  
  4859.  
  4860.  
  4861.  
  4862.  
  4863.  
  4864.  
  4865.  
  4866.  
  4867.  
  4868.  
  4869.  
  4870.  
  4871.  
  4872.  
  4873.  
  4874.  
  4875.  
  4876.  
  4877.  
  4878.  
  4879.  
  4880.                                      - 80 -
  4881.  
  4882.  
  4883.         APPENDIX 3: RESERVED FORTRAN KEYWORDS
  4884.  
  4885.         The  following  lists  show  the keywords and intrinsic functions
  4886.         from FORTRAN 77 and non-standard extensions (VAX, CDC, AIX, UNIX,
  4887.         ...) recognised by FFT. This list may not be complete or correct.
  4888.  
  4889.         Keywords  (standard  &  non-standard):  ACCEPT,  ASSERT,  ASSIGN,
  4890.         AUTOMATIC,   BACKSPACE,   BLOCKDATA,  BLOCK,  BYTE,  CALL,  CASE,
  4891.         CHARACTER,  CLOSE,  COMMON,  COMPLEX,  CONTINUE,  DATA,   DELETE,
  4892.         DICTIONARY,  DIMENSION,  DOUBLECOMPLEX,  DOUBLEPRECISION, DOUBLE,
  4893.         DOWHILE,  DO,  ELSEIF,  ELSE,  ENDDO,  ENDFILE,  ENDIF,   ENDMAP,
  4894.         ENDSELECT,   ENDSTRUCTURE,   ENDUNION,   ENDWHILE,   END,  ENTRY,
  4895.         EQUIVALENCE, EXTERNAL, FILE,  FORMAT,  FUNCTION,  GOTO,  GO,  IF,
  4896.         IMPLICITNONE,  IMPLICIT,  INCLUDE,  INQUIRE,  INTEGER, INTRINSIC,
  4897.         LOGICAL,  NAMELIST,  NONE,  OPEN,  PARAMETER,   PAUSE,   POINTER,
  4898.         PRECISION,  PRINT,  PROGRAM,  PUNCH,  READ, REAL, RECORD, RETURN,
  4899.         REWIND,  REWRITE,  SAVE,  SELECT,   SELECTCASE,   STATIC,   STOP,
  4900.         STRUCTURE,  SUBROUTINE,  THEN, TO, TYPE, UNION, UNLOCK, VOLATILE,
  4901.         WHILE, WRITE, $INCLUDE
  4902.  
  4903.         Intrinsic functions: ABS, ACHAR, ACOS, AIMAG, AINT, ALOG10, ALOG,
  4904.         AMAX0, AMAX1, AMIN0, AMIN1, AMOD, AND, ANINT, ASIN, ATAN2,  ATAN,
  4905.         CABS,  CCOS,  CEXP,  CHAR,  CLOG,  CMPLX, CONJG, COSH, COS, CSIN,
  4906.         CSQRT, DABS, DACOS, DASIN, DATAN2, DATAN, DBLE,  DCMPLX,  DCONJG,
  4907.         DCOSH,  DCOS, DDIM, DEXP, DFLOAT, DIMAG, DIM, DINT, DLOG10, DLOG,
  4908.         DMAX1, DMIN1, DMOD, DNINT,  DPROD,  DSIGN,  DSINH,  DSIN,  DSQRT,
  4909.         DTANH,  DTAN,  EPBASE,  EPEMAX,  EPEMIN,  EPHUGE, EPMRSP, EPPREC,
  4910.         EPTINY, EXP,  FLOAT,  FPABSP,  FPEXPN,  FPFRAC,  FPMAKE,  FPRRSP,
  4911.         FPSCAL,  IABS,  IACHAR,  ICHAR,  IDIM, IDINT, IDNINT, IFIX, IMAG,
  4912.         INDEX, INT, ISIGN, LEN, LGE, LGT, LLE, LLT, LOG10,  LOG,  LSHIFT,
  4913.         MAX0,  MAX1,  MAX,  MIN0,  MIN1,  MIN,  MOD, NINT, NOT, OR, REAL,
  4914.         RSHIFT, SIGN, SINH, SIN, SNGL, SQRT, TANH, TAN, XOR, ZABS,  ZCOS,
  4915.         ZEXP, ZLOG, ZSIN, ZSQRT,
  4916.  
  4917.         Non-standard intrinsic functions: ABORT,  ACOSD,  ASIND,  ATAN2D,
  4918.         ATAND, BTEST, CABS1, CAMAX, CAMIN, CASUM,  CAXPY,  CCOPY,  CDABS,
  4919.         CDCOS,  CDEXP,  CDLOG,  CDOTC,  CDOTU, CDSIN, CDSQRT, CMAX, CMIN,
  4920.         CNORM2, CNRM2, CNRSQ, COSD, CROTG,  CROT,  CSCAL,  CSET,  CSIGN1,
  4921.         CSIGN,  CSUM,  CSWAP,  CVCAL,  CZAXPY, DAMAX, DAMIN, DASUM, DATE,
  4922.         DAXPY, DCOPY, DDOT, DMAX,  DMIN,  DNORM2,  DNRM2,  DNRSQ,  DREAL,
  4923.         DROTG,  DROT,  DSCAL,  DSET,  DSUM, DSWAP, DVCAL, DZAXPY, ERRSNS,
  4924.         EXIT, GETARG, GETENV,  GMTIME,  HFIX,  I,  IARGC,  IAND,  IBCHNG,
  4925.         IBCLR,  IBITS,  IBSET,  ICAMAX,  ICAMIN,  ICMAX,  ICMIN,  IDAMAX,
  4926.         IDAMIN, IDATE, IDMAX, IDMIN, IEOR,  IOR,  IQINT,  IQNINT,  IRAND,
  4927.         ISAMAX,  ISAMIN, ISHA, ISHC, ISHFT, ISHFTC, ISMAX, ISMIN, IZAMAX,
  4928.         IZAMIN,  IZMAX,  IZMIN,  JFIX,  LTIME,  MVBITS,  NWORKERS,  QEXT,
  4929.         QFLOAT,  RAN,  RAND,  SAMAX,  SAMIN,  SASUM,  SAXPY, SCOPY, SDOT,
  4930.         SECNDS, SIND, SIZEOF, SMAX, SMIN, SNORM2,  SNRM2,  SNRSQ,  SRAND,
  4931.         SROTG,  SROT,  SSCAL,  SSET,  SSUM, SSWAP, SVCAL, SYSTEM, SZAXPY,
  4932.         TAND, TIME, ZAMAX, ZAMIN,  ZASUM,  ZAXPY,  ZCOPY,  ZDOTC,  ZDOTU,
  4933.         ZEXT, ZMAX, ZMIN, ZNORM2, ZNRM2, ZNRSQ, ZROTG, ZROT, ZSCAL, ZSET,
  4934.         ZSUM, ZSWAP, ZVCAL, ZZAXPY
  4935.  
  4936.         VAX specific built-in functions: %DESCR, %LOC, %REF, %VAL
  4937.  
  4938.  
  4939.  
  4940.  
  4941.                                      - 81 -
  4942.  
  4943.  
  4944.         APPENDIX 4: EFFICIENCY
  4945.  
  4946.         To  provide some values about the speed and the efficiency of the
  4947.         programs, tests were performed with CFT386 and CST386.
  4948.  
  4949.         One test with CFT386 (v2.21) was done with the source code of the
  4950.         C++ part of the GNU-C compiler  (version  2.2.2),  which  is  the
  4951.         largest of the three compiler parts (C,  C++,  Objective-C).  The
  4952.         test was made on a 33 MHz 80486,  8 MB RAM,  256 KB cache,  12 ms
  4953.         hard  disk,  2.5  MB  RAM-disk.  The command line options were -m
  4954.         -rauspPC_INCLUDE_PATH -TGNU -cs -Cs -n -W5 -G  -vn:\  -L+  -time.
  4955.         The following results have been found:
  4956.  
  4957.         -    137  files  (71 source files and 66 include files) have been
  4958.              scanned
  4959.         -    a total number of 2318 functions has been found  from  which
  4960.              2236 functions were defined in the 69 source files
  4961.         -    the  directed  call  graph  would  have 2302 nodes and 10276
  4962.              connections
  4963.         -    the critical function call path has a maximum nesting  level
  4964.              of 115
  4965.         -    the  total  size  of  the  137 files is 6.538 MB with 208900
  4966.              lines (about  31  bytes/line),  source  code/filesize  ratio
  4967.              0.712, average function size is 1956 bytes resp. 63 lines
  4968.         -    the  effective  size  of the preprocessed and scanned source
  4969.              code (source files and their included files)  is  20.990  MB
  4970.              with 602300 lines
  4971.         -    the resulting output file has about 3.921 MB and 36000 lines
  4972.         -    the resulting 6 database files have a size of 870 KB (source
  4973.              code/database ratio is about 7.5 : 1)
  4974.         -    inside  BRIEF,  a  database  search  for  the  location of a
  4975.              function is performed in less than 4 seconds
  4976.         -    the total time  for  the  complete  processing  was  21'57''
  4977.              minutes  (11'03''  for preprocessing,  8'13'' for analysing,
  4978.              1'00'' for output file writing, 1'32'' for database writing)
  4979.         -    the average speed for  this  source  code  was  about  1.080
  4980.              MB/min. respectively 31000 lines/min.
  4981.  
  4982.         Another test with CFT386 (v2.21) was done with a large commercial
  4983.         project.  The test was made on a 33 MHz 80486,  8 MB RAM,  256 KB
  4984.         cache,  12 ms hard disk,  no RAM-disk.  The command line  options
  4985.         were  -m+  -rausp -cs -Cs -n -time -cmdline -M -G -TMSC70,L -P -L
  4986.         -W5. The results:
  4987.  
  4988.         -    291 files (194 source files and 97 include files) have  been
  4989.              scanned
  4990.         -    a  total  number of 1955 functions has been found from which
  4991.              1866 functions were defined in the source files
  4992.         -    the total size of the 291 files is  15.719  MB  with  387600
  4993.              lines,  source  code/filesize ratio 0.531,  average function
  4994.              size is 2800 bytes resp. 100 lines
  4995.         -    the effective size of the preprocessed  and  scanned  source
  4996.              code  (source  files and their included files) is 220.685 MB
  4997.              with 2861000 lines
  4998.  
  4999.  
  5000.  
  5001.  
  5002.                                      - 82 -
  5003.  
  5004.  
  5005.         -    the total time for  the  complete  processing  was  161'02''
  5006.              minutes (139'43'' for preprocessing,  19'21'' for analysing,
  5007.              0'56'' for output file writing, 0'58'' for database writing)
  5008.         -    the average speed for  this  source  code  was  about  1.388
  5009.              MB/min. respectively 17990 lines/min.
  5010.  
  5011.         To  get  some  efficiency values for CST386 (v2.21),  the include
  5012.         files from another commercial  project  were  analysed  for  data
  5013.         types.  The  test  was made on a 33 MHz 80486,  8 MB RAM,  256 KB
  5014.         cache, 12 ms hard disk, no RAM-disk:
  5015.  
  5016.         -    52 include files have been scanned
  5017.         -    a total number of 605 data types have been found from  which
  5018.              567  structures/unions  were defined in 42 of the 54 include
  5019.              files
  5020.         -    the directed call  graph  would  have  588  nodes  and  1787
  5021.              connections
  5022.         -    the  total size of the 52 files is 1.384 MB with 25410 lines
  5023.              (about 54 bytes/line), source code/filesize ratio 0.342
  5024.         -    the resulting output file (options -rasp  -cs  -Cs  -n)  has
  5025.              about 378 KB and 8760 lines
  5026.         -    the resulting 6 database files have a size of 315 KB (source
  5027.              code/database ratio is about 4.4 : 1)
  5028.         -    the  total  time  for  the  complete  processing  was 0'43''
  5029.              minutes (0'17'' for analysis, 0'05'' for output file writing
  5030.              and 0'20'' for database writing)
  5031.         -    the average speed for  this  source  code  was  about  4.885
  5032.              MB/min.  respectively  89700  lines/min  (only analysis,  no
  5033.              preprocessing performed).
  5034.  
  5035.         Another test with CST386 (v2.21) was done  with  the  C++  source
  5036.         code  of  the Microsoft Foundation Class (MFC) 2.0.  The test was
  5037.         made on a 33 MHz 80486, 8 MB RAM, 256 KB cache,  12 ms hard disk,
  5038.         2.5   MB   RAM-disk.   The   command   line  options  were  -rasp
  5039.         -I\msvc\mfc\include -I\msvc\include -P -TMSVCWNT -C++  -D_WINDOWS
  5040.         -D_X86_  -Cs -n -b -W5 -time -G -vn:\ -L+.  The following results
  5041.         have been found:
  5042.  
  5043.         -    170 files (95 source files and 75 include files)  have  been
  5044.              scanned
  5045.         -    a  total number of 890 data types have been found from which
  5046.              701 were defined in the source and include files
  5047.         -    the directed call  graph  would  have  755  nodes  and  1402
  5048.              connections
  5049.         -    the  total size of the 170 files is 2.42 MB with 87500 lines
  5050.              (about 28 bytes/line), source code/filesize ratio 0.779
  5051.         -    the effective size of the preprocessed  and  scanned  source
  5052.              code  (source  files  and their included files) is 157.28 MB
  5053.              with 5580100 lines
  5054.         -    the total time for  the  complete  processing  was  106'20''
  5055.              minutes  (72'07''  for preprocessing,  33'14'' for analysis,
  5056.              0'12'' for output file writing, 0'44'' for database writing)
  5057.         -    the average speed  for  this  source  code  was  about  1.49
  5058.              MB/min. respectively 53000 lines/min.
  5059.  
  5060.  
  5061.  
  5062.  
  5063.                                      - 83 -
  5064.  
  5065.  
  5066.         The  calculated  average values for the analysis speed differ due
  5067.         to the effective size of the  'really'  present  source  code  in
  5068.         relation  to  the  size  of the comments which can be seen by the
  5069.         code/filesize ratio.  The speed values do not consider  that,  if
  5070.         the  preprocessing  option  -P  is set,  the source code is first
  5071.         preprocessed to a temporary file and then analysed  in  a  second
  5072.         step  so  that  large  parts  of  the  source code are read twice
  5073.         (original and preprocessed code) and written  once  (intermediate
  5074.         preprocessor output).
  5075.  
  5076.         With these facts in mind, the analysis speed of CFT and CST seems
  5077.         to be quite acceptable!
  5078.  
  5079.  
  5080.  
  5081.  
  5082.  
  5083.  
  5084.  
  5085.  
  5086.  
  5087.  
  5088.  
  5089.  
  5090.  
  5091.  
  5092.  
  5093.  
  5094.  
  5095.  
  5096.  
  5097.  
  5098.  
  5099.  
  5100.  
  5101.  
  5102.  
  5103.  
  5104.  
  5105.  
  5106.  
  5107.  
  5108.  
  5109.  
  5110.  
  5111.  
  5112.  
  5113.  
  5114.  
  5115.  
  5116.  
  5117.  
  5118.  
  5119.  
  5120.  
  5121.  
  5122.  
  5123.  
  5124.                                      - 84 -
  5125.  
  5126.  
  5127.         APPENDIX 5: SYSTEM REQUIREMENTS
  5128.  
  5129.         DOS real mode versions:
  5130.         -    IBM-AT or 100% compatible with Intel 80286 or higher, 640 KB
  5131.              RAM, hard-disk, MS-DOS 5.0 or higher
  5132.  
  5133.         DOS protected mode versions:
  5134.         -    IBM-AT  or 100% compatible with Intel 80386/80387 or higher,
  5135.              4 MB RAM (8 MB recommended), hard-disk, MS-DOS 5.0 or higher
  5136.              (NOTE: it is currently  not  known  if  the  protected  mode
  5137.              version will run with Windows 95 (MS-DOS 7.0))
  5138.  
  5139.         Windows 16 bit versions:
  5140.         -    IBM-AT  or 100% compatible with Intel 80386 or higher,  4 MB
  5141.              RAM (8 MB recommended),  hard-disk,  MS-DOS 5.0  or  higher,
  5142.              Windows 3.1 or Windows for Workgroups 3.11 (enhanced mode),
  5143.              VBRUN300.DLL (Visual Basic Run-Time library installed in the
  5144.              \windows\system  directory,   required  by  the  DLL  sample
  5145.              application SXTNVIEW)
  5146.  
  5147.         Windows 32 bit (Win32s) versions:
  5148.         -    IBM-AT or 100% compatible with Intel 80386 or higher,  8  MB
  5149.              RAM,  hard-disk,  Windows NT 3.1,  Windows 95, MS-DOS 5.0 or
  5150.              higher with Windows 3.1 or Windows for Workgroups  3.11  and
  5151.              Win32s subsystem (v1.25)
  5152.  
  5153.  
  5154.  
  5155.         APPENDIX 6: INSTALLATION
  5156.  
  5157.         See  the  appropriate  documentation  (INSTALL.DOC,  INSTALL.W32,
  5158.         INSTALL.NT, PROBLEMS.DOC, README,  ...) for information about the
  5159.         installation of the SXT programs.
  5160.  
  5161.  
  5162.  
  5163.  
  5164.  
  5165.  
  5166.  
  5167.  
  5168.  
  5169.  
  5170.  
  5171.  
  5172.  
  5173.  
  5174.  
  5175.  
  5176.  
  5177.  
  5178.  
  5179.  
  5180.  
  5181.  
  5182.  
  5183.  
  5184.  
  5185.                                      - 85 -
  5186.  
  5187.  
  5188.         APPENDIX 7: REVIEWS
  5189.  
  5190.         -    The  C  Users  Journal (Volume 12,  Number 1,  January 1994)
  5191.              (CXT)
  5192.  
  5193.         -    Professionelle Shareware 1/1993 (Computer Solutions Software
  5194.              GmbH) (CXT)
  5195.  
  5196.         -    Professionelle Shareware 3/1994 (Computer Solutions Software
  5197.              GmbH) (DXT, FXT, LXT)
  5198.  
  5199.         -    Shareware Professionell 11/1994 (Computer Solutions Software
  5200.              GmbH) (CXTWIN, DXTWIN, FXTWIN, LXTWIN)
  5201.  
  5202.  
  5203.  
  5204.  
  5205.  
  5206.  
  5207.  
  5208.  
  5209.  
  5210.  
  5211.  
  5212.  
  5213.  
  5214.  
  5215.  
  5216.  
  5217.  
  5218.  
  5219.  
  5220.  
  5221.  
  5222.  
  5223.  
  5224.  
  5225.  
  5226.  
  5227.  
  5228.  
  5229.  
  5230.  
  5231.  
  5232.  
  5233.  
  5234.  
  5235.  
  5236.  
  5237.  
  5238.  
  5239.  
  5240.  
  5241.  
  5242.  
  5243.  
  5244.  
  5245.  
  5246.                                      - 86 -
  5247.  
  5248.  
  5249.         APPENDIX 8: AVAILABILITY
  5250.  
  5251.         The SHAREWARE versions of the SXT programs can be  obtained  from
  5252.         various   shareware   vendors,   downloaded  from  many  Internet
  5253.         FTP-sites and mailboxes and found  on  several  CD-ROM  shareware
  5254.         collections.  The following list is not complete,  only the known
  5255.         vendors,  FTP-sites (only primary sites  where  the  software  is
  5256.         uploaded by the author) or CD-ROM's are shown.
  5257.  
  5258.         VENDORS:
  5259.         -    Computer  Solutions  Software  (CSL)  GmbH,  Postfach  1180,
  5260.              D-85561 Grafing, GERMANY
  5261.  
  5262.         -    PEARL Agency, Am Kalischacht 4, D-79426 Buggingen, GERMANY
  5263.  
  5264.         -    EMS Professional Software,  4505 Buckhurst  Ct.,  Olney,  MD
  5265.              20832-1830, U.S.A.
  5266.  
  5267.         -    The  C-Users'  Group  (CUG),  1601 W.  23rd St.,  Suite 200,
  5268.              Lawrence, KS 66046, U.S.A. (CXT: CUG Library Disk # 391)
  5269.  
  5270.         -    Public Brand Software / Ziff-Davies Interactive,  Cambridge,
  5271.              MA 02141, U.S.A. (distributes through Public Brand Software,
  5272.              ZiffNet on CompuServe, ZiffNet on Prodigy, and Interchange)
  5273.  
  5274.         -    Limelight Media Inc.,  P.O. Box 3536, Terre Haute, IN 47803,
  5275.              U.S.A. (Platinum Shareware CD-ROM Series)
  5276.  
  5277.         -    AMUG CD,  Inc.,  4131 N.  24th Street  #A-120,  Phoenix,  AZ
  5278.              85016, U.S.A.
  5279.  
  5280.         FTP:
  5281.         -    SIMTEL: ftp.coast.net
  5282.              (directories: CXT: SimTel/msdos/c, DXT: SimTel/msdos/dbase,
  5283.              FXT:   SimTel/msdos/fortran,   LXT:   SimTel/msdos/misclang,
  5284.              CXTWIN/  FXTWIN/   LXTWIN:   SimTel/win3/pgmtools,   DXTWIN:
  5285.              SimTel/win3/database)
  5286.  
  5287.         -    CICA: ftp.cica.indiana.edu
  5288.              (directory for SXT Windows versions: pub/pc/win3/programr)
  5289.  
  5290.         -    GARBO: garbo.uwasa.fi
  5291.              (directories:  CXT: pc/c-lang,  DXT/FXT/LXT: pc/programming,
  5292.              SXT Windows versions: /windows/programming)
  5293.  
  5294.         CD-ROM:
  5295.         -    The C-Users' Group (CUG) Library on CD-ROM
  5296.              (The C-Users' Group (CUG),  1601 W.  23rd  St.,  Suite  200,
  5297.              Lawrence, KS 66046, U.S.A.)
  5298.  
  5299.         -    CSL-MEGA CD Vol. 6
  5300.              CSL-MEGA CD Vol. 7
  5301.              CSL-MEGA CD Vol. 9
  5302.              (Computer  Solutions  Software  (CSL)  GmbH,  Postfach 1180,
  5303.              D-85561 Grafing, GERMANY)
  5304.  
  5305.  
  5306.  
  5307.                                      - 87 -
  5308.  
  5309.  
  5310.         -    Algorithmen fuer C und C++
  5311.              (Addison-Wesley)
  5312.  
  5313.         There are also several CD-ROMs available containing the  complete
  5314.         collection  of  files  from the SIMTEL,  CICA and GARBO FTP-sites
  5315.         which may also include some or all of the SXT programs.
  5316.  
  5317.         BOOKS:
  5318.         Two books are annouced which will include SXT programs on CD-ROM.
  5319.         The books are called 'Windows Shareware Programming  Tools'  (R&D
  5320.         Publications) and 'Windows 95 Secrets' (IDG Books).
  5321.  
  5322.  
  5323.  
  5324.                           (THIS DOCUMENT HAS 88 PAGES)
  5325.  
  5326.  
  5327.  
  5328.  
  5329.  
  5330.  
  5331.  
  5332.  
  5333.  
  5334.  
  5335.  
  5336.  
  5337.  
  5338.  
  5339.  
  5340.  
  5341.  
  5342.  
  5343.  
  5344.  
  5345.  
  5346.  
  5347.  
  5348.  
  5349.  
  5350.  
  5351.  
  5352.  
  5353.  
  5354.  
  5355.  
  5356.  
  5357.  
  5358.  
  5359.  
  5360.  
  5361.  
  5362.  
  5363.  
  5364.  
  5365.  
  5366.  
  5367.  
  5368.                                      - 88 -
  5369.